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27. Errors and Debugging 



The first portion of this chapter explains how programs can handle errors, by means of 
condition handlers. It also explains how a program can signal an error if it detects something it 
doesn't like. 

'["he second explains how users can handle errors, by means of an interactive debugger; that 
is, it explains how to recover if you do something wrong. A new user of the Lisp Machine, or 
someone who just wants to know how to deal with errors and not how to cause them, should 
ignore die first section and skip ahead to section 27.7, page 578. 

Hie remaining sections describe some other debugging facilities. Anyone who is going to be 
writing programs for tlie Lisp Machine should familiarize himself with these. 

The irace facility provides the ability to perform certain actions at the time a function is 
called or at the time it returns. The actions may be simple typeout, or more sophisticated 
debugging fi.inctions. 

The advise facility is a somewhat similar facihty for modifying die behavior of a function. 

The breakon facility allows you to cause die debugger to be entered when a certain function is 
called. You can then use the debugger's stepping commands to step to die next fimction call or 
return. 

The step facility allows the evaluation of a form to be intercepted at every step so that the 
user may examine just what is happening throughout die execution of die form. Stepping works 
only on interpreted code. 

The MAR facility provides the ability to cause a trap on any memory reference to a word (or 
a set of words) in memory. If something is getting clobbered by agents unknown, diis can help 
track down the source of die clobberage. 

27.1 Conditions 

Programmers often want to control what action is taken by Uieir programs when errors or 
other exceptional situations occur. Usually different situations arc handled in different ways, and 
in order to express what kind of handling each situation should have, each situation must have an 
associated name. In Zetalisp, noteworthy events are represented by objects called condition 
instances. When an event occurs, a condition instance is created; it is then signaled, and a 
handler for that condiuon may be invoked. 

When a condition is signalled, die system (essentially) searches up die stack of nested function 
invocations looking for a handler established to handle diat condition. The handler is a fiinction 
diat gets called to deal with the condition. The condition mechanism itself is just a convenient 
way for finding an appropriate handler function for a particular exceptional situation. 
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When a condition is signaled, a condition instance is created to represent the event and hold 
information about it. This information includes condition names then classify the condition and 
any other data that is likely to be of interest to condition handlers. A condition instance is 
immutable once it has been created. Some conditions are errors, which means tliat the debugger 
is invoked if tliey are signaled and not handled. 

Condition instances are flavor instances. The flavor condition is the base flavor from which 
all flavors of condition are built. Several operations tliat are defined on condition instances are 
described below. The flavor error, which is built on condition, is tlie base flavor for all kinds of 
conditions which are errors. 

A condition name is a symbol then is used to identify a category of conditions. Each 
condition instance possesses one or more condition names. Each condition handler specifies one or 
more condition names tliat it should apply to. A handler applies to a condition if they have any 
condition names in common. This is the sole purpose of condition names: to match condition 
instances with tlieir handlers. TTie meaning of every condition name signaled by the system is 
described in tliis manual. ITie condition name index is a directory for tliem. Conditions then are 
errors possess the condition name error. 

In PL/I, CLU, ADA and most other systems that provide named conditions, each condition 
has only one name. That is to say, the categories identified by condition names are disjoint. In 
Zetalisp, each condition instance can have multiple condition names, which means tiiat the 
categories identified by condition names can overlap and be subdivided. 

For example, among the condition names defined by the system are condition, error, 
sys:arithmetic- error, sys:negative-sqrt and sys:divide-by-zero. condition is a condition name 
that all condition instances posess. error identifies the category of conditions tlien are considered 
errors. sys:arithmetic -error identifies tlie category of errors that pertain to arithmetic operations. 
sys:negative-sqrt and sys:divide-by-zero are the most specific level of categorization. So, the 
condition signaled when you evaluate (sqrt -1) will possess condition names sys:negative-sqrt, 
sys:arlthmetic -error, error and condition, while the one signaled if you evaluate (// 1 0) will 
possess condition names sys:divide-by-zero, sys:arithmetic -error, error and condition. In this 
example, die categories fall into a strict hierarchy, but this does not need to be the case. 

Condition names are documented throughout the manual, with definitions like this: 

sys:divide-by-zePO (sys: arithmetic -error error) Condition 

Tlie condition name sys:divide-by-zero is always accompanied by sysiarithmetic-error 

and error (that is, it categorizes a subset of those categories). The presence of error 
implies that all sys:divide-by-zero conditions are errors. 

The condition instance also records additional information about the event. The condition 
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operation by returning this number. The condition instance signaled by dividing by zero handles 
the ifunction operation by returning the function that did the division (it might be truncate, 
floor, ceiling or round, as well as //). In general, for each condition name there are 
conventions saying what additional information is provided and what operations to use to obtain 
it. 
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1 he fla\or of the condition instance is always one of tlie condition names, and so arc its 
component flavors (with a few exceptions; si:vanilla-flavor and some other flavor components are 
omitted, since they arc not useful categories for condition handlers to specify). In our example, 
the flavor of the condition is sys:arithmetic -error, and its components include error and 
condition. Condition names require new flavors only when they require significantly different 
handling by the error system; you will understand in detail after finishing this section. 

condition-typep condition- instance cotidit ion- name 

Returns t if condition-instance possesses condition name condition- name. 

errorp object 

Returns t if object is a condition instance and its flavor incorporates error. ITiis is 
nonnally equivalent to (typep object ':error). Some functions such as open optionally 
return tlie condition instance rather tlian signaling it, if an error occurs, errorp is useful 
in testing the value returned. 

: CO nd it ion -names 0/7cra//o/i (w condition 

Returns a list of all the condition names possesses by tliis condition instance. 

27.2 Handling Conditions 

A condition handler is a ftmction that is associated with certain condition names (categories of 
conditions), fhe variable eh :condition- handlers contains a list of the handlers that are current; 
handlers are estiiblished using special forms which bind this variable. When a condition is 
signaled, tliis list is scanned and all tlie handlers which apply arc called, one by one, until one of 
the handlers cither throws or returns non-nil. 

Since each new handler is pushed onto the front of eh:condition- handlers, the innermost- 
established handler gets the first chance to handle the condition. When the handler is run, 
eh:condition-handlers is bound so that the running handler (and all tJie ones that were 
established farther in) are not in effect. This avoids the danger of infinite recursion due to an 
error in a handler invoking the same handler. 

One tiling a handler can do is throw to a tag. Often the *catch for this tag is right next to 
the place where the handler is esuiblished, but tliis does not have to be so. A simple handler 
that applies to all errors and just throws to a tag is established using ignore -errors. 

ignore-errors body... Special Form 

Any error within the execution of body causes control to return from the ignore-errors 
form. In this case, the first value is nil and the second is non-nil. If there is no error 
inside body, the values of the last form in the body are returned from the ignore-errors 
form. 

The handler can also ask to pr(x:eed from the condition. This is done by returning a non-nil 
value. See the section on proceeding, page 569, for more information. 

The handler can also decline to handle the condition, by returning nil. Then the next 
applicable handler is called, and so on until eitlier some handler does handle the condition or 
there are no more handlers. 
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The handler function is called in tlie environment where the condition was signaled, and in 
the same stack group. All special variables have tlie values they had at the place where the 
signaling was done, and all catch tags tliat were available at the point of signaling may be tlirown 
to. 

ITie handler receives the condition instance as its first argument. When estiiblishing tlic 
handler, you can also provide additional arguments to pass to the handler when it is called. This 
allows the same function to be used in varying circumstances. 

A second list of handlers is called eh:condition-default-handlers. This list is scanned after 
all of eh:condition- handlers has been used up; tliat is tlie only difference between the two lists. 
The handlers work tlie same way. 

The fundamental means of establishing a condition handler is the special fonn condition - 
bind. 

condition-bind {handlers...) body... Special Fonn 

condition-bind-default {handlers...) body... Special Form 

A condition -bind form looks like this: 

{condition-bind {( conditions handler- fonn additional- arg-fonns . . .) 
{conditions handler-form additional- arg-fonns . . .)) 
body. . . ) 

The purpose is to execute body with one or more condition handlers established. 

Each list of conditions and handler-form establishes one handler, conditions is a condition 
name or a list of condition names to which tlie handler should apply. It is not evaluated. 
handler-form is evaluated to produce the fimction that is the actual handler. The 
additional- arg-fonns are evaluated, on entry to the condition -bind, to produce additional 
arguments that will be passed to the handler fijnction when it is called. The arguments to 
the handler function will be the condition instance being signaled, followed by the values 
of any additional- arg-fonns. 

conditions can be nil; then the handler will apply to all conditions that are signaled. In 
this case it is up to the handler fijnction to decide whether to do anything. It is 
important for the handler to refrain from handling certain conditions that are used for 
debugging, such as break and si:call-trap. The :debugging -condition -p operation on 
condition instances will return non-nil for these conditions. Certain other conditions such 
as sys:virtual- memory-overflow should be handled only with great care. The 
:dangerous-condition-p operation returns non-nil for these conditions. 

condition-bind-default is like condition -bind but establishes a default handler instead of 
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different order: first all the applicable ordinary handlers are given a chance to handle die 
condition, and then the default handlers get their chance. A more flexible way of doing 
things like this is described under signal -condition (page 568). 



SRC:<I..MAN>HRR0RS.TEXT.81 24-JAN-83 



Handling Conditions 556 IJsp Machine Manual 



Condition handlers tliat simply tlirow to the fiinction tliat cst^iblishcd them are very common, 
so tlicre arc special constructs provided for defining tliem. 

condition-case {variables...) body- form clauses... Special Fonn 

(condition-case {variable) 
body-fonn 
{condition- names fonns. . . ) 
{condition- names forms. . . ) 

body-form is executed with a condition handler established tliat will throw back to the 
condition -case if any of the specified condition names is signaled. 

Each list starting with some condidon names is a clause, and specifies what to do if one 
of tliose condition names is signaled, condition-names is either a condition name or a list 
of condition names; it is not evaluated. 

Once the handler per se has done the tlirow, the clauses are tested in order until one is 
found tliat applies, fliis is almost like a selectq, except that the signaled condition can 
have several condition names, so the first clause that matches any of diem gets to run. 
Ihe forms in die clause are executed with variable bound to die condition instance diat 
was signaled. The values of the last form in die clause are returned from the condition - 
case form. 

If none of tlie specified conditions is signaled during the execution of body-form (or if 
other handlers, established within body-fonn, handle diem), Uicn die values of body-form 
are returned from tlic condition -case form. 

variable may be omitted if it is not used. 

It is also possible to have a clause starting with :no-error in place of a condition name. 
This clause is executed if body-form finishes normally. Instead of just one variable diere 
can be several variables; during die execution of the :no -error clause, these are bound to 
die values returned by body-fonn. The values of die last form in die clause become die 
values of die condition -case form. 

Here is an example: 

(condition-case ( ) 
(print foo) 
(error (format t " «Error in printing»") ) ) 

cond1tion-can {[variable]^ body- form clauses... Special Form 

condition -call is an extension of condition -case diat allows you to give each clause an 
arbitrary conditional expression instead of just a list of condition names. It looks like diis: 
(condition-call {variable) 
body-form 
{predicate forms. . . ) 
{predicate forms. . . ) 
...) 
The difference between diis and condition -case is die predicate in each clause. The 
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clauses in a condition -call resemble the clauses of a cond rather tlian tJiosc of a selectq. 

When a condition is signaled, each predicate is executed while still within the environment 
of the signaling (that is, within the actual handler function), predicate may refer to 
variable to sec the condition instiince. If any predicate returns non-nil, then the handler 
throws to tlic condition -call and tlie corresponding clause's fonns are executed, if every 
predicate returns nil, the condition is not handled by this handler. 

In fact, each predicate is computed a second time after the throw has occurred in order to 
decide which clause to execute. The code for the predicate is copied in two different 
places, once into the handler function to decide whether to dirow, and once in a cond 
which follows tlie catch. 

variable may be omitted if it is not used; but it is unlikely that you will not need to use 
it. 

Hxample: 

(condition-call (instance) 
(do-it) 
((and (condi tion-typep instance ' f s :f i le-error) 

(not (condi tion-typep instance 'fs: no-more-room) ) ) 
(compute-wh at- to- return)) ) 
The condition name fs:no- more- room is a subcategory of fs:file-error; thus, this will 
handle all file errors except for fs:no- more-room. 

Each of the four condition handler establishing special forms has a conditional version tliat 
decides at run ume wheUier to establish tlie handlers. 

condition-b1nd-if cond-fonn {handlers...) body... Special Form 

( condi tion-bi nd-if cond-form 

( {conditions handler-fonn additional- arg- forms. . . ) 
{conditions handler-form additional- arg- f orms . . . ) ) 
body. . . ) 
begins by executing cond-fonn. If it returns non-nil, then all proceeds as for a regular 
condition -bind. If cond-form returns nil, then the body is still executed but without the 
condition handler. 

condit1on-case-1f cond-fonn {variables...) body- form clauses... Special Form 

(condition-case-if cond-fonn {variable) 
body-form 
{condition- names forms. . . ) 
{condition- names forms. . . ) 
...) 
begins by executing cond-fonn. If it returns non-nil, then all proceeds as for a regular 
condition -case. If cond-fonn returns nil, then the bodyfonn is still executed but without 
the condition handler, body-fonns values are returned, or, if there is a :no -error clause, 
it is executed and its values returned. 
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condition-call-if cond-form ([variable]) body-fonn clauses. . . Special Form 

(condition-call-if cond-form [variable) 
body-fonn 
[predicate forms. . . ) 
[predicate forms. . . ) 
...) 
begins by executing cond-form. If it returns non-nil, then everything proceeds as for a 
regular condition -call. If cond-fonn returns nil, tlien the body-fonn is still executed but 
without the condition handler. In that case, body-fonn's values are always returned. 

condition-bind-def ault-if cond-fonn [handlers...) body... Special Fonn 

Tliis is used just like condition -bind -if, but establishes a default handler instead of an 
ordinary handler, 

eh: condition-handlers Variable 

This is tlie list of established condition handlers. Each element looks like this: 

[condition- names function additional-arg- values. . . ) 
condition- names is a condition name or a list of condition names, or nil which means all 
conditions. 

fiinction is the actual handler function. 

additional-arg- values are additional arguments to be passed to die function when it is 
called, functions first argument is always the condition instance. 

Both the links of die value of ehxonditlon-handlers and the elements are usually created 
with with -stack -list, so copy diem if you want to save diem for any period of time. 

eh: condition-default-handlers Variable 

This is die list of established default condition handlers. The data format is the same as 
diat of eh condition -handlers. 



27.3 Standard Condition Flavors 

condition Flavor 

The flavor condition is die base flavor of all conditions, and provides a default definition 
of all the operations described in diis chapter. 

condition incorporates si:property-list-mixin, which defines operations :get and :plist. 
Each property name on the property list is also an operation name, so diat sending the 
:foo message is equivalent to (send instance ':get ':foo). 

condition also provides two instance variables, eh:format-string and eh:format-args. 
condition's mcdiod for die the :report operation passes these to format to print die error 
message. 
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error Flavor 

The flavor error makes a condition an error condition, errorp returns t for such 
conditions, and tlie debugger is entered if tiiey are signaled and not otherwise handled. 

sys:no-act1on-mixin Flavor 

This mixin provides a definition of the proceed type :no-action. 

sys:proceed-with-value-mixin Flavor 

Phis mixin provides a definition of the proceed type :new-vaiue. 

f error Flavor 

This flavor is a mixture of error, sys:no -action -mixin and sys:proceed -with -value - 
mixin. It is the flavor used by default by tlie functions terror and cerror, and is often 
convenient for users to instantiate. 

sys: warning Flavor 

This flavor is a mixture of sys:no-action-mixin and condition. 

sys:bad-array-mixin Flavor 

This mixin provides a definition of the proceed type :new-array. 

27.4 Condition Operations 

Every condition instance can be asked to print an error message which describes the 
circumstances that led to the signaling of the condition. The easiest way to print one is to print 
the condition instance without slashification (princ, or format operation -A). This actually uses 
Lhe :report operation, which implements the printing of an error m.essage. When a condition 
instance is printed with slashification, it uses the # c syntax so that it can be read back in. 

: report stream Operation on condition 

Prints on stream the condition's error message, a description of the circumstances for 
which the condition instance was signaled. The output should neither start nor end with a 
carriage return. 

If you are defining a new flavor of condition and wish to change the way the error 
message is printed, this is the operation to redefine. All others use this one. 

: report-string Operation ow condition 

Returns a string containing the text that the :report operation would print. 

Operations provided specifically for condition handlers to use: 

:dangerous-condition-p Operation on con6\{\on 

Returns t if the condition instance is one of those that indicate events that are considered 
extremely dangerous, such as running out of memory. Handlers that normally handle all 
conditions might want to make an exception for these. 
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: debugging-condi tion-p Operation o// condition 

Returns t if tlie condition instance is one of those tJiat are signaled as part of debugging, 
such as break, which is signaled when you type Meta- Break, i'hese conditions are not 
errors, although tJiey will normally enter the debugger; this serves to prevent most 
condition handlers from handling diem, iiut any condition handler which is written to 
handle all conditions should probably make a specific exception for these. 

See also the operations proceed -types and proceed -type -p, which have to do with 
proceeding (page 569). 

27.4.1 Condition Operations for the Debugger 

Some operations are intended for tlie debugger to use. 'Hiey are documented because some 
flavors of condition redefine them so as to cause the debugger to behave differently. This section 
is of interest only to advanced users. 

rprint-error-message stack-group brief-flag stream Operation on cor\6\\.\on 

Ihis operation is used by tlie debugger to print a complete error message. This is done 
primarily using tlie :report operation. 

Certain flavors of condition define a :after :print-error-message method which, when 
brief-flag is nil, prints additional helpful information which is not part of the error 
message per se. Often diis requires access to the stack group in addition to the data in 
the condition instance. The method can assume that if brief-flag is nil then stack-group is 
not the one which is executing. 

For example, the condition signaled when you call an undefined flmction will check for 
the case of calling a fi.mction such as bind that is meaningful only in compiled code; if 
that is what happened, it will search die stack to look for the name of die function in 
which die call appears. This is information diat is not considered crucial to die error 
itself, and is dierefore not recorded in die condition instance. 

:maybe-c1ear-1nput stream Operation on condWlon 

This operation is used on entry to die debugger to discard input. Certain condition 
flavors, used by stepping redefine this operauon to do nothing, so diat die input will not 
be discarded. 

: bug -report- recipient- system Operation on condWion 

The value returned by diis operation is used to determine what address to mail bug 
reports to, when die debugger Control -M command is used. By default, it returns 
"LISPM". The value is passed to the fiinction bug. 

:bug-peport-descr1ption stream «feoptional Operation on cond'iWon 

numeric-arg 
ITiis operadon is used by die Control -M command to print on stream the information 
that should go in the bug report, numeric-arg is the numeric argument, if any, Uiat die 
user gave to the Control -M command. 



SRC;<L.MAN>HRR0RS.TEXT.81 24-.IAN-83 



.isp Machine Manual 561 Signaling Conditions 



: find-current-frame slack-group Operaiion on condition 

Returns the stack indices of Lhc stack frames tliat the debugger should operate on. 

l^hc first value is the frame "at which the error occurred." ITiis is not the innermost stack 
frame; it is outside the calls to such functions as ferror and signal -condition which were 
used to signal the error. 

I'he second value is the initial value for the debugger command loop's current frame. 

The third value is the innermost frame that tlie debugger should be willing to let the user 
see. By default this is the innermost active frame, but it is safe to use an open but not 
active frame within it. 

The fourth value, if non-nil, tells tlie debugger to consider the innermost frame to be 
"interesting". Normally, frames that are part of the interpreter (calls to *eval, si:apply- 
lambda, prog, cond, etc.) are considered uninteresting. 

This is a flavor operation so that certain flavors of condition can redefine it. 

: debugger-command- loop stack-group &optional Operation on con&iWon 

error- object 
Enters the debugger command loop. The initial error message and backtrace have already 
been printed. This message is sent in an error handler stack group; stack-group is the 
stack group in which the condition was signaled, error-object is the condition object which 
was signaled; it defaults to the one the message is sent to. 

This operation uses :or method combination (see section 20.11, page 350). Some 
condition flavors add methods that perform, som.e other sort of processing or enter a 
different command loop. For example, unbound variable errors look for look-alike 
symbols in other packages at this point. If the added method returns nil, the original 
metliod that enteres the usual debugger command loop is called. 

27.5 Signaling Conditions 

Signaling a condition has two steps, creating a condition instance and signaling the instance. 
There are convenience interface functions that combine the two steps. You can also do them 
separately. If you just want to signal an error and do not want to worry much about condition 
handling, the fimction ferror is all you need to know. 
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27.5.1 Convenience Functions for Signaling 

terror &rcst make- condition- arguments 

terror creates a condition instance using make -condition and then signals it with signal - 
condition, specifying no local proceed types, and with t as the use-debugger argument so 
the debugger is always entered if tlie condition is not otherwise handled. 

I'he first argument to terror is always a signal name (often nil). 1'he second argument is 
usually a format string and the remaining arguments are additional arguments for format; 
but this is under the control of the definition of the signal name. Example: 
(ferror 'sys: negati ve-sqrt 

"You cannot take the square root of ~S." number) 
For compatibility with the Symbolics system, if the first argument to terror is a string, 
then a signal name of nil is assumed. The arguments to ferror are passed on to make- 
conditlon with an additional nil preceding them. 

If you prefer, you can use the formatted output functions (page 422) to generate the error 
message. Here is an example, though in a simple case like this using format is easier: 
(ferror ' sys: negati ve-sqrt 

(format :outfmt "You cannot take the square root of " 

(prinl number) ".") 
number) 
In this case, arguments past the second one are not used for printing the error message, 
but the signal name may still expect tliem to be present so it can put them in the 
condition instance. 

cerror proceed- type ignore &rest make- condition- arguments 

Creates a condition instance by passing the make- condition- arguments to make -condition 
and then signals it. \^ proceed- type is non-nil tlien it is provided to signal-condition as a 
proceed type. For compatibility with old uses of cerror, if proceed-type is t, :new-value 
is provided as the proceed type. If proceed-type is :yes, :no-action is provided as the 
proceed type. 

The second argument to cerror is not used and is present for historical compatibility. It 
may be given a new meaning in the future. 

If a condition handler or the debugger decides to proceed, the second value it returns 
becomes the value of cerror. 

check- arg varname predicate description [type-symbol\ Macro 

The check -arg form is useful for checking arguments to make sure that they are valid. 
A simple example is: 

(check-arg foo stringp "a string") 
foo is the name of an argument whose value should be a string, stringp is a predicate of 
one argument, which returns t if the argument is a string, "a string" is an English 
description of the correct type for die variable. 
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The general form of check-arg is 
(check-arg varname 

predicate 

description 

type-symbol) 
var-name is the name of the variable whose value is of tlie wrong type. If the error is 
proceeded, this variable will be setq'ed to a replacement value, predicate is a test for 
whether the variable is of the correct type. It can be either a symbol whose function 
definition takes one argument and returns non-nil if die type is correct, or it can be a 
non-atomic form diat is evaluated to check the type and that presumably contains a 
reference to the variable var-name. description is a string that expresses predicate in 
English, to be used in error messages, type-symbol is a symbol tliat is used by condition 
handlers to determine what type of argument was expected. It may be omitted if it is to 
be tlie same as predicate, which must be a symbol in that case. 

The use of tlie type-symbol is not really well-defined yet, but the intention is that if it is 
numberp (for example), the condition handlers can tell that a number needed, and might 
may to convert the actual supplied value to a number and proceed. 

[We need to establish a conventional way of "registering" the type-symbols to be used for 
various expected types. It might as well be in tlie form of a table right here.] 

The predicate is usually a symbol such as fixp, stringp, listp, or closurep, but when 
there isn't any convenient predefined predicate, or when die condition is complex, it can 
be a fonn. In this case you should supply a type- symbol that encodes the type. For 
example: 

(check-arg a 

(and (numberp a) (< a 10.) (> a 0.)) 

"a number from one to ten" 

one-to-ten) 
If this error got to the debugger, die message 

The argument a was 17, which is not a number from one to ten. 
would be printed. 

In general, what constitutes a valid argument is specified in three ways in a check-arg. 
description is human-understandable, type-symbol is program-understandable, and predicate 
is executable. It is up to the user to ensure that tiiese diree specifications agree. 

check-arg uses predicate to detennine whether the value of die variable is of die correct 
type. If it is not, check-arg signals die sys:wrong -type -argument condition (see page 
38). If a handler proceeds, using proceed type :new -value, die variable is set to die 
value proceeded with, and check-arg starts over, checking die type again. 

check-arg- type var-name type-name [description] Macro 

This is a useful variant of die check-arg form. A simple example is: 

(check-arg foo :number) 
too is die name of an argument whose value should be a number, inumber is a value 
diat is passed as a second argument to typep (sec page 11); diat is, it is a symbol diat 
specifies a data type. The English form of die type name, which gets put into die error 
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message, is found automatically. 

The general form of check -arg- type is: 
{ check-arg-type var-name 
type- name 
description) 
var-name is the name of the variable whose value is of the wrong type. If the error is 
proceeded tliis variable will be setq'ed to a replacement value, type-name describes the 
type that the variable's value ought to have. It can be exactly those things acceptable as 
tlie second argument to typep. description is a string that expresses predicate in Fjiglish, 
to be used in error messages. It is optional. If it is omitted, and type-name is one of the 
keywords accepted by :typep, which describes a basic Lisp data type, tJien the right 
description will be provided correctly. If it is omitted and type-name describes some other 
data type, then tlie description will be the word "a" followed by the printed 
representation of type-name in lower-case. 

The remaining signaling fimctions are provided for compatibility only. 

error &rest make- condition- arguments 

error exists for compatibility with Maclisp and the Symbolics version of ZeUilisp. It takes 
arguments in three patterns: 

(error string object \_interrupt'\) 
which is used in Maclisp, and 

(error condition-instance) 

(error flavor-name init-options. . . ) 
which are used by Symbolics. (In fact, die arguments to error are simply passed along to 
make -condition if tliey do not appear to fit the Maclisp pattern). 

If the Maclisp argument pattern is not used, dien there is no difference between error 
and terror. 

f signal format-string &rest format-args 

This function is for Symbolics compatibility only, and is equivalent to 

(cerror ' : no-action nil nil format-string fonnat-args . . . ) 

signal signal- name &rest remaining-make- condition- arguments 

The signal-name and remaining-make-condition-arguments are passed to make -condition, 
and the result is signaled with signal -condition. 

If the remaining-make-condition-arguments are keyword arguments and iproceed -types is 
one of the keywords, the associated value is used as the list of proceed types. In 
particular, if signal-name is actually a condition instance, so that the remaining arguments 
will be ignored by make-condition, it works to specify the proceed types this way. 

If the proceed types are not specified, a list of all the proceed types that the condition 
instance knows how to prompt the user about is used by default. 
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err set form \flag\ Special Vonn 

The errset special fonn catches errors during the evaluation of fbnn. If an error occurs, 
the usual error message is printed unless flag is nil. llien control is thrown and the 
errset-fonri returns nil. flag is evaluated first and is optional, defaulting to t. If no error 
occurs, the value of the errset-form is a list of one element, the value of fonn. 

errset is implemented in an ad-hoc fashion, which is still supported so that old compiled 
code will continue to run. It may be changed in the future to compile using condition - 
case. Meanwhile, many uses of errset or errset-hke constructs really ought to be 
checking for more specific conditions instead. 

catch-error fonn [flag] Special Form 

catch -error is a variant of errset. This special form catches errors during the evaluation 
of fonn and returns two values. Normally the first value is the value of fonn and the 
second value is nil. If an error occurs, the usual error message is printed unless flag is 
nil, and tlien control is tlirown out of tlie catch -error form, which returns two values, 
first nil and second a non-nil value tliat indicates the occurrence of an error, flag is 
evaluated first and is optional, defaulting to t. 

errset Variable 

If this variable is non-nil, errset forms are not allowed to trap errors. The debugger is 

entered just as if tliere were no errset. This is intended mainly for debugging. The initial 
value of errset is nil. 

err Special Form 

This is for Maclisp compatibility only and should not be used. 

(err) is a dumb way to cause an error. If executed inside an errset, that errset returns 
nil, and no message is printed. Otherwise an unseen throw-tag error occurs. 

(err fonn) evaluates form and causes tlie containing errset to return the result. If executed 
when not inside an errset, an unseen throw-tag error occurs. 

(err form flag), which exists in Maclisp, is not supported. 

27.5.2 Creating Condition Instances 

You can create a condition instance quite satisfactorily with make -instance if you know 
which instance variables to initialize. For example, 

(make-instance 'ferror ': condition-names '(foo) 
' :format-string "~S loses." 
' :format-args losing-object) 
creates an instance of ferror just like the one that would be signaled if you do 
(ferror 'foo "~S loses." losing-object) 

Note that the flavor name and its components' names are added in automatically to whatever 
you specify for the :condition- names keyword. 
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Direct use of make- instance is cumbersome, however, and it is usually handier to define a 
signal name with defsignal or defsignal -explicit and then create tlie instance with make- 
condition. 

A signal name is a sort of abbreviation for all the things thai are always the same for a 
certain sort of condition: the flavor to use, the condition names, and what arguments are 
expected. In addition, it allows you to use a positional syntax for the arguments, which is usually 
more convenient than a keyword syntax in simple use. 

Here is a typical defsignal: 

{defsignal series-not-convergent sys : arithmetic-error (series) 
"Signaled by limit extractor when SERIES does not converge.") 
This defines a signal name series-not-convergent, together with the name of the flavor to use 
(sysiarithmetJc -error, whose meaning is being stretched a little), an interpretation for the 
arguments (series, which will be explained below), and a documentation string. The 
documenujtion string is not used in printing tlie error message: it is documentation for the signal 
name. 

series -not -convergent could then be used to signal an error, or just to create a condition 
instance, like this: 

(ferror 'series-not-convergent 

"The series ~S went to infinity." myseries) 

(make-condi tion 'series-not-convergent 

"The series ~S went to infinity." myseries) 

ITie list (series) in the defsignal is a list of implicit instance variable names. They arc 
matched against arguments to make-condition following the format string, and each implicit 
instance variable name becomes an operation defined on the condition instance to return the 
corresponding argument. (You can imagine that igettable- instance -variables is in effect for all 
the implicit instance variables.) In this example, sending a iseries message to the condition 
instance will return the value specified via myseries when the condition was signaled. TTie 
implicit instance variables arc actually implemented using the condition instance's property list. 

Ihus, defsignal spares you the need to create a new flavor merely in order to remember a 
particular datum about the condition. 

defsignal signal-name {flavor condition-names...) Special Form 

implicit-instance-variables documentation extra- init- keyword- forms 
Defines signal-name to create an instance o^ flavor with condition names condition- names, 
and implicit instance variable whose names are taken from the list implicit-instance- 
variables and whose values are taken from the make- condition arguments following the 
format string. 

Instead of a list {flavor condition- names...) tiiere may appear just a flavor name. This is 
equivalent to using signal-name as the sole condition name. 
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The extra- inil-keym)rd- forms arc forms to be evaluated to produce additional keyword 
arguments to pass to make -instance. These can be used to initialize other instance 
variables tliat particular flavors may have. These expressions can refer to the implicit- 
instance- variables. 

def s i gnal -exp licit signal-name {flavor condition- names...) Special Fortn 
signal-arglist documentation in it- keyword- forms... 

Like defsignal, defsignal -explicit defines a signal name. This signal name is used the 

same way, but the way it goes about creating the condition instance is different. 

First of all, there is no list of implicit instance variables. Instead, signal-arglist is a 
lambda list which is matched up against all the arguments to make-condition except for 
the signal-name itself. The variables bound by tlic lambda list can be used in the init- 
keyword-fortns, which are evaluated to get arguments to pass to make -instance. For 
example: 

(def signal-explicit niysignal-3 

(my-error-f lavor mysignal-3 my-signals-category ) 
{format-string losing-object Strest format-args) 

"The third kind of thing I like to signal." 

' rfonnat-string format-string 

' :f ormat-args (cons losing-object (copylist format-args)) 

': losing-object-name (send losing-object ':name)) 
Since implicit instance variables are really just properties on the property list of the 
instance, you can create tliem by using init keyword :property-list. The contents of the 
property list determines what implicit instance variables there will be and their values. 

make-condition signal-name &rest arguments 

make -condition is the fundamental way tliat condition instances are created. The signal- 
name says how to interpret the arguments and come up with a flavor and values for its 
instance variables. The handling of the arguments is entirely determined by the signal- 
name. 

If signal-name is a condition instance, make-condition returns it. It is not useful to call 
make-condition tliis way explicitly, but tliis allows condition instances to be passed to 
the convenience functions error and signal which call make-condition. 

If the signal-name was defined with defsignal or defsignal-explicit, then that definition 
specifics exactly how to interpret the arguments and create the instance. In general, if the 
signal-name has an eh:make-condition-function property (which is how defsignal works), 
this property is a function to which the signal-name and arguments are passed, and it does 
the work. 

Alternatively, the signal-name can be the name of a flavor. Tncn the argumenis are 
passed to make -instance, which interprets them as init keywords and values. This mode 
is not really recommended and exists for compatibility with Symbolics software. 

If the signal-name has no eh:make-conditlon -function property and is not a flavor name, 
then a trivial defsignal is assumed as a default. It looks like this: 
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(defsignal signal-name ferror ()) 
So the value is an instiincc of ferror, with the signal-name as a condition name, and the 
arguments arc interpreted as a format string and args for it. 

'I'he signal-name nil actually has a definition of this form, nil is frequently used as a 
signal name in the fi.niction ferror when there is no desire to use any condition name in 
particular. 

27.5.3 Signaling a Condition Instance 

Once you have a condition instance, you are ready to invoke the condition handling 
mechanism by signaling it. A condition instance can be signaled any number of times, in any 
stack groups. 

signal -condition condition- instance &optional proceed-types invoke- debugger 
ucode- error- status inhibit- resume- handlers 
Invoke the condition handling mechanism on condition- instance. The list of proceed-types 
says which proceed types (among those conventionally defined for the type of condition 
you have signaled) you are prepared to implement, should a condition handler return one 
(see "proceeding"). These are in addition to any pr(x:eed types implemented nonlocally by 
condition -resume special forms. 

signal -condition returns to its caller only if it decides to proceed using one of the 
proceed- types . or if the condition is not an error and there are no nonlocal proceed types 
to be used, or if inhibit- resume- handlers is non-nil. 

ucode- error- status is used for internal purposes in signaling errors detected by the 
microcode. 

signal -condition tries various possible handlers for the condition. Each handler that is tried 
can terminate the act of signaling by throwing out of signal -condition, or it can specify a way to 
proceed from the signal. The handler can also decline to handle the condition, and then the next 
possible handler is tried. 

First eh condition -handlers is scanned for handlers that are applicable (according to the 
condition names they specify) to this condition instance. After this list is exhausted, 
eh:conditlon-default- handlers is scanned the same way. 

Finally, if invoke- debugger is non-nil, the debugger is the handler of last resort. With the 
debugger, the user can ask to throw or to proceed. ITie default value of invoke- debugger is non- 
nil if the condition- instance is an error. 

It is possible for all handlers to decline the condition, if the debugger is not among the 
handlers tried. (The debugger cannot "decline to handle the condition".) In this circumstance, 
signal -condition proceeds using the first proceed type on the list of available ones, provided it is 
a nonlocal proceed type. If it is a local proceed type, or if there arc no proceed types, signal- 
condition just returns nil. (It would be slightly simpler to proceed using the first proceed type 
whether it is local or not. But in the case of a local proceed type, this would just mean returning 
the proceed type instead of nil. It is considered slightly more useful to return nil, allowing the 
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signaler to distinguish the case of a condition not handled. The signaler knows which proceed 
types it specified, and can easily consider nil as equivalent to tlie first of them.) 

Otherwise, by this stage, a proceed type has been chosen from the available list. If the 
proceed type was among those specified by the caller of signal-condition, then proceeding 
consists simply of returning to that caller, llie chosen proceed type is the first value, and 
arguments (returned by tlie handler along with the proceed type) may follow it. if the proceed 
type was implemented nonlocally with condition -resume (see page 575), tlien tlie associated 
proceed handler function on eh condition -resume -handlers is called. 

If inhibit- resume-handlers is non-nil, resume handlers are not invoked. If a handler returns a 
nonlocal proceed type, signal -condition just returns to its caller as if the proceed type were local. 
If the condition is not handled, signal -condition returns nil. 

'Vhd purpose of condition -bind -default is so that you can define a handler that will handle 
an error only if it is not handled by any of tlie callers' handlers. A more flexible technique for 
doing this sort of tiling is to make the condition handler signal the same condition instance 
recursively by calling signal -condition, like this: 
(multiple-value-list 

(signal-condition condition- instance 

eh-.condi tion-proceed-types nil nil t)) 
This passes along the same list of proceed types specified by tlie original signaler, prevents the 
debugger from being called, and prevents resume handlers from being run. If the first value 
signal -condition returns is non-nil, one of the outer handlers has handled the condition; your 
handler's simplest option is to return those same values so that the other handler has its way (but 
you could also examine tlicm and return modified values). Otherwise, you go on to handle the 
condition in your default manner. 

ehitrace-conditions Variable 

1 his variable may be set to a list of condition names to be traced. Whenever a condition 
possessing a traced condition name is signaled, an error is signaled to report the fact. 
(lYacing of conditions is turned oflF when this error is signaled). Proceeding with proceed 
type :no- action causes the signaling of the original condition to continue. 

If eh:trace-conditions is t, all conditions are traced. 



27.6 Proceeding 

Both condition handlers and the user (through the debugger) have the option of proceeding 
certain conditions. 

Co^v. ^rvrirjuj/^n namn ron Hpfinp ac 3 mnvfTitinn certain nrnceed tvoes. which are keywords 
that signify a certain conceptual way to proceed. For example, condition name sys:wrong-type- 
argument defines the proceed type :argument-value which means, "Here is a new value to use 
as the argument." 

Each signaler may or may not implement all the proceed types which are meaningful in 
general for the condition names being signaled. For example, it is ftitile to proceed from a 
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sys:wrong-type-argument error with :argument-value unless the signaler knows how to take the 
associated value and store it into the argument, or do something else that fits the conceptual 
specifications of :argument-value. For some signalers, it may not make sense to do this at all. 
Therefore, one of the arguments to signal -condition is a list of the proceed types that this 
particular signaler knows how to handle. 

In addition to the proceed types specified by the individual signaler, other proceed types can 
be provided nonlocally; they are implemented by a resume handler which is in effect Uirough a 
dynamic scope. See below, section 27.6.3, page 575. 

A condition handler can use the operations :proceed -types and proceed -type -p on the 
condition instance to find out which proceed types are available, it can request to proceed by 
returning one of the available proceed types as a value. This value is returned from signal - 
condition, and the condition's signaler can take action as appropriate. 

If the handler returns more than one value, the remaining values are considered arguments of 
tlie proceed type. The meaning of the arguments to a proceed type, and what sort of arguments 
are expected, are part of the conventions asscKiated with the condition name tliat gives the 
proceed type its meaning. For example, the :argument- value proceed type for sys: wrong -type - 
argument errors conventionally takes one argument, which is the new value to use. All the 
values returned by the handler are returned by signal -condition to the signaler. 

Here is an example of a condition handler that proceeds from sys:wrong -type-argument 
errors. It makes any atom effectively equivalent to nil when used in car or any other function 
that expects a list. The handler uses the :description operation, which on sys:wrong-type- 
argument condition instances returns a keyword describing the data type that was desired, 
(condition-bind 

( ( sys : wrong- type -argument 
#'(lambda (condition) 

(if (eq (send condition ' :description) ':cons) 
(values ' :argument-value nil))))) 
body. . . ) 

Here the argument to the :argument -value proceed type is nil. 

: proceed types Operation on cond'\i\on 

Returns a list of the proceed types available for this condition instance. This operation 
should be used only within the signaling of the condition instance, as it refers to the 
special variable in which signal -condition stores its second argument. 

:proceed-type-p proceed- type Operation on condition 

t if proceed-type is one of the proceed types available for this condition instance. This 
operation should be used only within the signaling of the condition instance, as it refers 
to the special variable in which signal -condition stores its second argument. 
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27.6.1 Proceeding and the Debugger 

If the condition invokes the debugger, then the user has the opportunity to proceed. ITiis too 
uses a proceed type. When the debugger is entered, each of the available proceed types is 
assigned a command character starting with Super-A. Each character becomes a command to 
proceed using the corresponding proceed type. 

Three additional facilities are required to make it convenient for the user to prcxreed using the 
debugger. Each is provided by methods defined on condition flavors. When you define a new 
condition flavor, you must provide metliods to implement these facilities. 

Documentation: 

It must be possible to tell the user what each proceed type is for. 

Prompting for arguments: 

The user must be asked for the arguments for the proceed type. Each proceed type may 
have different arguments to ask for. 

Not always the same proceed types: 

Usually the user can choose among the same set of proceed types that a handler can, but 
sometimes it is useflil to provide the user with a few extra ones, or to suppress some of 
them for him. 

These three facilities are provided by methods defined on condition flavors. Each proceed 
type that is provided by signalers should be accompanied by suitable methods. This means that 
you must nonnally define a new flavor if you wish to use a new proceed type. 

The :document-proceed-type operation is supposed to print documentation of what a 
proceed type is for. For example, when sent to a condition instance describing an unbound- 
variable error, if the proceed type specified is :new-value, the text printed will be something like 
"Proceed, reading a value to use instead." 

: document-proceed- type proceed-type stream Operation on cond'iWon 

Prints on stream a description of the purpose of proceed type proceed-type. Tliis operation 
uses icase method combination (see section 20.11, page 350), to make it convenient to 
define the way to document an individual proceed type. The string printed should start 
with a third person singular verb form, in lower case, and end with a period. 

As a last resort, if the condition instance has a icase method for :proceed -asking -user 
with proceed-type as the subopcration, and this method has a documentation string, it is 
printed, lliis is in fact the usual way that a proceed type is documented. 

The :proceed -asking -user operation is supposed to ask for suitable arguments to pass with 
the proceed type. Sending :proceed-asking-user to an instance of sysiunbound -variable with 
argument :new -value would read and evaluate one expression, prompting appropriately. 
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:proceed-asking-usep proceed- type coni read-object-fn Operation oucor^d'sWon 

The method for proceed -asking -user embodies the knowledge of how to prompt for 
and read the additional arguments tliat go with proceed-type. 

:case method combination is used (sec section 20.11, page 350), making it possible to 
define the handling of each proceed type individually in a separate fimction. 'llie 
documentation string of the :case method for a proceed type is also used as the default 
for :document-proceed-type on that proceed type. 

7"hc method for :proceed -asking -user should read values by calling read-object-fn, using 
a calling sequence like that of prompt -and -read. 1he read-object-fn may or may not 
actually use prompt-and-read. After reading the appropriate number and sort of values 
to go with the particular proceed type, tlic method should call die continuation cont with 
a proceed type and suitable arguments (presumably based on what the user typed). The 
proceed type passed to cont need not be tlie same as the one given to :proceed -asking - 
user; it should be one of the proceed types available for handlers to use. 

Here is how sys: proceed -with- value -mixin provides for the prweed type :new-value: 
(defmethod (proceed-wi t h -value-mi xin 

:case : proceed-asking-user :new-value) 
(continuation re ad-object- function) 
"Proceeds, reading a value to use instead." 
(funcall continuation ':new-value 

(funcall read-object-function 
' :eval-read 

"~&Form whose value to use instead: "))) 
Note die documentation string, which is provided for die sake of the :document- proceed -type 
operation. 

The :user- proceed -types operation is given die list of proceed types actually available and is 
supposed to return die list of proceed types to offer to die user. By default, Uiis operation 
returns its argument: all proceed types are available to die user dirough die debugger. 

For example, die condition name sys:unbound -variable conventionally defines die proceed 
types :new-value and :no-action. The first specifies a new value; the second attempts to use die 
variable's current value and gets another error if the variable is sdll unbound. These are clean 
operations for handlers to use. But it is more convenient for die user to be offered only one 
choice, which will use die variable's new value if it is bound now, but otherwise ask for a new 
value. 'Jhis is implemented wiUi a : user -proceed -types mediod Uiat replaces die two proceed 
types with a single one. 

Or, you might wish to offer die user two different proceed types that differ only in how diey 
ask the user for additional informaUon. For handlers, diere would be only one proceed type. 
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ruser-proceed-types pwceed-types Operation a« condition 

Assuming that pwceed-types is tlic list of proceed types available for condition handlers to 
return, this operation returns tlic list of proceed types that the debugger should offer to 
the user. 

Only the proceed types offered to the user need to be handled by :document - proceed - 
type and :proceed -asking -user. 

The flavor condition itself defines tJiis to return its argument. Other condition flavors 
may redefine this to filter the argument in some appropriate fashion. 

:pass-on method combination is used (see section 20.11, page 350), so that if multiple 
mixins define methods for :u3er- proceed -types, each method will get a chance to add 
or remove pr(x:eed types. The methods should not actually modify the argument, but 
should cons up a new list in which certain keywords are added or removed according to 
the other keywords that are there. 

Elements should be removed only if they are specifically recognized. ITiis is to say, the 
method should make sure that any unfamiliar elements present in the argument are also 
present in the value. Arranging to omit certain specific pr(x;eed types is legitimate; 
returning only the intersection with a constant list is not legitimate. 

Here is an example of nontrivial use of :user- proceed -types: 
(defflavor my-error () (error)) 

(defmethod (my-error :user-proceed-types) (proceed-types) 
(if (memq ':foo proceed-types) 

(cons ' :foo-two-args proceed-types) 
proceed-types)) 

(defmethod (my-error :case :proceed-asking-user :foo) 
(cont read-object-f n) 
"Proceeds, reading a value to foo with." 
(funcall cont ':foo 

(funcall read-object-fn ':eval-nead 
"Value to foo with: "))) 

(defmethod (my-error :case :proceed-asking-user :foo-two-args) 
(cont read-object-fn) 
"Proceeds, reading two values to foo with." 
(funcall cont ' :foo 

(funcall read-object-fn ':eval-read 

"Value to foo with: ") 
(funcall read-object-fn ':eval-read 

"Value to foo some more with: "))) 

In this example, if the signaler provides the proceed type :foo, then it is described for the 
user as "proceeds, reading a value to foo with"; and if the user specifies that proceed type, he 
will be asked for a single value, which will be used as the argument when proceeding. In 
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addition, tiic user will be offered tlic proceed type :foo-two-args, which has its own 
documentation and which reads two values. But for condition handlers there is really only one 
pr(x:ced type, :foo. :foo-two-args is just an alternate interface for tlie user to proceed type :foo, 
and this is why the :user-proceed -types method offers :foo-two-args only if the signaler will 
accept :foo. 

27.6.2 Ho>v Signalers Provide Proceed Types 

Each condition name defines a conceptual meaning for certain proceed types, but this does 
not mean that all of those proceed types may be used every time the condition is signaled. The 
signaler must specifically implement the proceed types in order to make them do what they are 
conventionally supposed to do. For some signalers it may be difficult to do, or may not even 
make sense. For example, it is no use having a proceed type :store- new- value if die signaler 
does not have a suitable place to store, pennanently, the argument the handler supplies. 

Therefore, we require each signaler to specify just which proceed types it implements. Unless 
the signaler explicidy specifies proceed types one way or another, no proceed types are allowed 
(except for nonlocal ones, described in the following section). 

One way to specify the proceed types allowed is to call signal -condition and pass the list of 
proceed types as the second argument. 

Another way that is less general but more convenient is signal -proceed -case. 

signal -proceed-cas8 {{variables...) make-condition-arguments...) Special Form 

clauses... 
signal -proceed -case is a convenient special form for signaling a condition and providing 
proceed types. Each clause specifies a proceed type to provide, and also contains code to 
be run if a handler should proceed with that proceed type. 

( signal -proceed-case ( {argument- mrs...) 

signal- name signal- name- arguments. . . ) 
{proceed- type forms. . . ) 
{proceed- type forms. . .) 

A condition-object is created with make -condition using the signal-name and signal-name- 
arguments', then it is signaled giving a list of die proceed types from all the clauses as the 
list of proceed types allowed. 

The variables argument-vars are bound to the values returned by signal-condition, except 
for the first value, which is tested against the proceed-type from each clause, using a 
selectq. llie clause diat matches is executed. 
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Example: 

(defsignal my-wrong-type-arg 

{eh: wrong -type -argument-error sys : wrong- type -argument) 
(old-value arg-name description) 

wrong type ai yum«3iiu I I vjiii iiij Own ouus. J 



{signal -pro ceed-c as e 
{ ( newarg) 
'my-wrong-type-arg 

"The argument ~A was ~S, which is not a cons." 
'foo foo 'cons) 
( :argument-value (car newarg))) 
The signal name my-wrong-type-arg creates errors with condition name sys: wrong -type - 
argument. 'Ihc signal -proceed -case shown signals such an error, and handles the proceed type 
:argument-value. If a handler proceeds using that proceed type, the handler's value is put in 
newarg, and tlien its car is returned from the signal -proceed -case. 

27.6.3 Nonlocal Proceed Types 

When the caller of signal -condition specifies proceed types, these are called local proceed 
types. They arc implemented at the point of signaling. There are also nonlocal proceed types, 
which are in effect for all conditions (with appropriate condition names) signaled during the 
execution of tlie body of the establishing special form. 

The most general form for establishing a resume handler is condition -resume. For example, 

in 

(condition- resume 

' (fs:f ile-error :retry-open t 

("proceeds, opening the file again.") 
(lambda (ignore) (*throw 'tag nil))) 
(do-forever 

(*catch 'tag (return (open pathname))))) 
the proceed type :retry-open is available for all fs:file-error conditions signaled within the call to 
open. 

condition- resume handler-form &body body Special Form 

condition- resume- if cond-fonn handler-form &body body Special Form 

Executes body with a resume handler in effect for a nonlocal proceed type according to 
the value of handler-form. For condition-resume-if, the resume handler is in effect only 
if cond-fonn s value is non-nil. 

The value of the handler-form should be a list with at least five elements: 
( condition-names proceed- type predicate format- string- and- args 
handler-function additional- args ) 
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condii ion- names is a condition name or a list of them. The resume handler applies to 
tliosc conditions only. 

pwcecd-type is the proceed type implemented by this resume handler. 

predicate is eitlicr t or a function that is applied to a condition instance and determines 
whether the resume handler is in effect for that condition instance. 

formal- string- and- args is a list of a string and additional arguments that can be passed to 
format to print a description of what tliis proceed type is for. 

handler-function is the ftmction called to do the work of proceeding, once this pnxrecd 
type has been returned by a condition handler or the debugger. Its arguments are the 
condition instance and the additional- args. 

For condition handlers there is no distinction between local and nonlocal pr(x:eed types. They 
are both included in the list of available proceed types returned by the :proceed -types operation 
(all the local proceed types come first), and the condition handler selects one by returning the 
prcx:ced type and any conventionally associated arguments. The debugger's : user -proceed -types, 
:document- proceed -type and :proceed -asking -user operations are also used the same way. 

The difference comes after tlie handler or the debugger returns to signal -condition. If the 
proceed type is a local one (one of tliose in the second argument to signal-condition), signal- 
condition simply returns. If tlic proceed type is not there, signal -condition looks for the 
handler-function associated with the proceed type, and calls it. 'ITie arguments to the handler 
function are the condition instance, the additional-args specified in the resume handler, and any 
arguments returned by the condition handler in addition to the proceed type. The handler 
function is supposed to do a throw. If it returns to signal -condition, an error is signaled. 

You are allowed to use "anonymous" nonlocal proceed types, which have no conventional 
meaning and are not specially known to the :document- proceed -type and :proceed -asking - 
user operations. The anonymous proceed type need not even be a symbol, and in practice they 
are frequently lists consed at run time (often using with -stack -list) to make sure they are all 
distinct. The default definition of proceed -asking -user handles an anonymous proceed type by 
simply calling the continuation passed to it, reading no arguments. The default definition of 
:document- proceed -type handles anonymous proceed types by passing format the fonnat-string- 
and-args list found in the resume handler (this is what that list is for). 

Anonymous proceed types are treated like other proceed types except as noted above. Proceed 
types that are lists are treated a little bit specially. For one thing, they are all put at the end of 
the list returned by the :proceed -types operation. For another, the debugger command 
Control -C or Resume, which normally proceeds using the first proceed type on that list, will not 
operate at all if that proceed type is a list 

Anonymous proceed types are usually created with some variant of error- restart. 
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error- restart [condition- names fonnat-string format- args...) Special Form 

body... 

error- restart- loop Special Form 

catch -err OP- res tart Special Form 

catch-error- restart- if cond-fonn [coudiiion- names Special Form 
format-string formal-args..) body... 
Fxecutes body with an anonymous resume handler for condition-names, condition- names is 

either a single condition name or a list of them, or nil meaning all conditions; it is not 
evaluated. 

formal-string and the formal-args, all of which are evaluated, are used by the 
:document- proceed -type operation to describe tlie anonymous proceed type. 

If the proceed type is used for proceeding, the automatically generated resume handler 
function does a throw back to tlie error- restart and the body is executed again from the 
beginning. If body returns, the values of the last form in it are returned from the error- 
restart form. 

error -restart -loop is like error -restart except that it loops to the beginning of body 
even if body completes normally. It is like enclosing an error-restart in a do-forever. 

catch -error- restart is like error -restart except that it never loops back to die beginning. 
If the anonymous proceed type is used for proceeding, tlie catch -error-restart form 
returns with nil as the first value and a non-nil second value. 

catch -error- restart -if is like catch -error- restart except that the resume handler is only 
in effect if the value of the cond-fonn is non-nil. 

All of these variants of error-restart can be written in terms of condltion-resume-if. 

error- restart forms often specify (error sys:abort) as the condition- names. ITie presence of 
error causes tliem to be listed (and assigned command characters) by the debugger, for all errors, 
and the presence of sys:abort causes tlie Abort key to use them. These forms are typically used 
by any sort of command loop, so that aborting within the command loop returns to it and reads 
another command, error -restart -loop is often right for simple command loops, catch-error- 
restart is useful when aborting should terminate execution rather than retry, or with an explicit 
conditional to test whether a throw was done. 

eh:invoke-resume-handler condition- instance proceed- type &rest args 

Invokes tlie innermost applicable resume handler for proceed-lype. Applicability of a 
resume handler is determined by matching its condition names against tliose possessed by 
condition- instance and by applying its predicate, if not t, to condition- instance. 

If proceed-type is nil, the innermost applicable resume handler is invoked regardless of its 
proceed type. However, in this case, the scan stops if t is encountered as an element of 
eh condition -resume -handlers. 
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ehicondition-resume-handleps Variable 

The current list of resume handlers for nonlocal proceed types, condition -resume works 
by binding this variable. Hlements are usually lists that have the format described above 
under condition -resume. The symbol t is also meaningful as an element of tliis list, it 
tenninates tlie scan for a resume handler when it is made by signal -condition for a 
condition tliat was not handled, t is pushed onto tlie list by break loops and the 
debugger to shield the evaluation of your type-in from automatic invocation of resume 
handlers established outside tlie break loop or the error. 

The links of this list, and its elements, are often created with with-stack-list. so be 
careful if you try to save the value outside tlie context in which you examine it. 

sys: abort (condition) Condition 

'Ihis condition is signaled by the Abort key; it is how that key is implemented. Most 
command loops use some version of error -restart to set up a resume handler for 
sys:abort so that it will return to tlie innermost command loop if (as is usually tlie case) 
no handler handles it. These resume handlers usually apply to error as well as sys:abort, 
so that the debugger will offer a specific command to return to the command loop. 

27.7 The Debugger 

When an error condition is signalled and no handlers decide to handle the error, an 
interactive debugger is entered to allow the user to look around and see what went wrong, and to 
help him continue the program or abort it. lliis section describes how to use the debugger. 

27.7.1 Entering the Debugger 

There are two kinds of errors: those generated by the Lisp Machine's microcode, and those 
generated by Lisp programs (by using ferror or related ftjnctions). When there is a microcode 
error, the debugger prints out a message such as the following: 

»TRAP 5543 (TRANS-TRAP) 

The symbol FOOBAR is unbound. 

While in the function *E\/AL <- SI :LISP-T0P-LEVEL1 

The first line of this error message indicates entry to the debugger and contains some 
mysterious internal microcode infomiation: the micro program address, the microcode trap name 
and parameters, and a microcode backtrace. Users can ignore this line in most cases. ^Fhe second 
line contains a description of the error in English. The third line indicates where the error 
happened by printing a very abbreviated "backtrace" of the stack (sec below); in tlie example, it 
is saying that the error was signalled inside the function *eval, which was called by siilisp -top- 
level 1. 

Here is an example of an error from Lisp code: 

»ERROR: The argument X was 1, which is not a symbol, 
While in the function FOO <- *EVAL «- SI : LISP-TOP-LEVELl 
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Here the first line contains the HngHsh description of the error message, and the second line 
contains tlie abbreviated backtrace, foo signalled the error by calling terror; however, terror is 
censored out of the backtrace. 

After tlie debugger's initial message, it prints the function that got the error and its 
arguments, llien it prints a list of commands you can use to proceed from the error, or to abort 
to various command loops. The possibilities depend on the kind of error and where it happened, 
so the list is different each time; that is why tlie debugger prints it. 'ITic commands in the list all 
start with Super-A, Super-B and continue as far as is necessary. 

eh:*inhibit-debugger-proceed-prompt* Variable 

If this is non-nil, the list of Super commands is not printed when die debugger is 
entered. Type Help X to see the list. 

debug-io Variable 

The debugger uses this stream for its I/O. Normally, tlie value is a synonym stream 
which indirects to tlic value of terminal -io. 

The value of this variable in the stack group in which the error was signaled is the one 
that counts. 

The debugger can be manually entered either by causing an error (e.g. by typing a ridiculous 
symbol name such as ahsdgf at the Lisp read-eval-print loop) or by typing die Break key with 
die Meta shift held down while the program is reading from the terminal. Typing tlic Break key 
with both Control and Meta held down will force die program into die debugger immediately, 
even if it is running. If die Break key is typed without Meta, it puts you into a read-eval-print 
loop using die break function (see page 644) radier into die debugger. 

eh process 

Stops process and calls die debugger on it so that you can look at its current state. Exit 
die debugger with die Control -Z command and eh will release die process and return. 
process can be a window, in which case the window's process will be used. 

If process is not a process but a stack group, the current state of die stack group will be 
examined. The caller should ensure diat no one tries to resume diat stack group while 
die debugger is looking at it. 

27.7.2 How to Use the Debugger 

Once inside die debugger, the user may give a wide variety of commands. This section 
describes how to give die commands, dien explains diem in approximate order of usefulness. A 
summary is provided at die end of the listing. 

When die debugger is waiting for a command, it prompts with an arrow: 
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If the error took place in the evaluation of an expression that you typed at the debugger, you 
are in a second (or deeper) level error. The number of arrows in the prompt indicates the depth. 

The debugger will also warn you about certain unusual circumstances that may cause 
paradoxical results. If default-cons-area is anything except working -storage -area, a message 
to tliat efTeQb^is printed. If base and ibase are not tlie same, a message is printed. ^., 

At this point, you may type either a Lisp expression or a command; a Control or Meta 
character is interpreted as a command, whereas most nonnal characters are interpreted as the first 
character of an expression. If you type tlie Help key or the ? key, you will get some 
introductory help with the debugger. 

If you type a Lisp expression, it will be interpreted as a Lisp form and will be evaluated in 
the context of the function which got the error. That is, all bindings which were in effect at the 
time of the error will be in effect when your form is evaluated, with certain exceptions explained 
below. The result of the evaluation will be printed, and the debugger will prompt again with an 
arrow. If, during the typing of the fonn, you change your mind and want to get back to the 
debugger's command level type the Abort key or a Control -G; tlie debugger will respond with 
an arrow prompt. In fact, at any time that typein is expected from you, while you are in the 
debugger, you may type Abort or Control -G to flush what you are doing and get back to 
command level. This read -eval- print loop maintains the values of +, *, and -just as the top- 
level one does. 

If an error occurs in the evaluation of tlie Lisp expression you type, you will get into a 
second invocation of the debugger, looking at the new error. The prompt will be " ". You can 
abort the computation and get back to tlie first error by typing the Abort key (see below). 
However, if the error is trivial the abort will be done automatically and tJie original error message 
will be reprinted. 

Various debugger commands ask for Lisp objects, such as an object to return or the name of 
a catch-tag. Whenever it tries to get a Lisp object from you, it expects you to type in a form; it 
will evaluate what you type in. This provides greater generality, since there are objects to which 
you might want to refer tliat cannot be typed in (such as arrays). If the form you type is non- 
trivial (not just a constant form), the debugger will show you the result of the evaluation, and 
ask you if it is what you intended. It expects a Y or N answer (see the function y-or-n-p, page 
620), and if you answer negatively it will ask you for another form. To quit out of the 
command, just type Abort or Control -G. 

Note that the variable bindings are those in effect at the point of error, not those of the 
current frame being looked at. Ihc Meta-S and Control- Meta -S commands allow you to look 
at the bindings in effect at the current frame. A few variables are rebound by the debugger itself, 
so you you must use Meta-S to find the values they had at the point of error: 

terminal -io terminal -io is rebound to the stream the debugger is using. 

standard -input 
standard -output 

standard -input and standard -output are rebound to be synonymous with 

terminal -io. 
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* + and * are rebound to iJic debugger's previous form and previous value. When 

the debugger is first entered, + is the last form typed, which is typically tlie one 
tliat caused tlie error, and * is the value of the previous fonn. 

evalhook 

si:applyhook These variables (see page 598) are rebound to nil, turning off tlie step facility if 
it was in use when the error occurred. 

eh:condition-handlers 

eh :condition -default- handlers 

These are rebound to nil, so that errors occurring within forms you type while in 
tlie debugger do not magically resume execution of the erring program. 

ehxondition - resume - handlers 

To prevent resume handlers established outside the error from being invoked 
automatically by deeper levels of error, this variable is rebound to a new value, 
which has an element t added in tlie front. 



27.7.3 Debugger Commands 

All debugger commands are single characters, usually with tlie Control or Meta bits. 'The 
single most useful command is Abort (or Control -Z), which exits from tlie debugger and throws 
out of the computation that got the error. ITiis is tlie Abort key, not a 5-letter command. Often 
you are not interested in using tlie debugger at all and just want to get back to Lisp top level; so 
you can do this in one character. 

If the error happened while you were innocently using a system utility such as the editor, 
then it represents a bug in the system. Report tlie bug using the debugger com.m.and Control -M. 
l^his gives you an editor preinitialized with the error message and a backtrace. You should type 
in a precise description of what you did tliat led up to the problem, tlien send the message by 
typing End. Be as complete as possible, and always give the exact commands you typed, exact 
filenames, etc. rather then general descriptions, as much as possible. The person who investigates 
the bug report will have to try to make the problem happen again; if he does not know where to 
find your file, he will have a difficult time. 

ITie Abort command signals the sys:abort condition, returning control to the most recent 
command loop. This can be Lisp top level, a break, or the debugger command loop associated 
with another error. Typing Abort multiple times will tlirow back to successively older read-eval- 
print or command loops until top level is reached. Typing Meta -Abort, on the other hand, will 
always throw to top level. Meta-Abort is not a debugger command, but a system command that 
is always available no matter what program you are in. 

Note that typing Abort in the middle of typing a form to be evaluated by the debugger 
aborts that form and returns to the debugger's command level, while typing Abort as a debugger 
command returns out of the debugger and tlie erring program, to the previous command level. 
Typing Abort after entering a numeric argument just discards the argument. 
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Sclf-documcntalion is provided by the Help or ? command, which types out some 
documentation on the debugger commands, including any special commands that apply to the 
particular error currently being handled. 

Often you want to try to proceed from the error. When the debugger is entered, it prints a 
table of commands you can use to proceed, or abort to various levels. The commands are 
Super-A, Super-B, and so on. How many there are and what they do is different each time 
there is an error, but the table says what each one is for. If you want to see the tiible again, 
type Help followed by X. 

The Resume (or Control -C) command is usually synonymous with Super-A. But Resume 
only proceeds, never aborts. If diere is no way to proceed, just ways to abort, tlien Resume will 
not do anything. 

The debugger knows about a current stack frame, and tliere are several commands that use it. 
The initially current stack frame is the one which signalled tlic error, cither the one which got the 
microcode-detected error or the one which called terror, cerror, or error. When the debugger 
starts it up it shows you this frame in tlie following format: 
FOO: 

Arg (X): 13 

Arg 1 (Y): 1 
and so on. ITiis means tJiat foo was called with two arguments, whose names (in the Lisp source 
code) are x and y. The current values of x and y are 13 and 1 respectively. These may not be 
the original arguments if foo happens to setq its argument variables. 

The Clear- Screen (or Control -L) command clears the screen, retypes the error message that 
was initially printed when the debugger was entered, and prints out a description of the current 
frame, in the above format. 

Several commands are provided to allow you to examine the Lisp control stack and to make 
frames current other than the one tliat got tlie error. The control stack (or "regular pdl") keeps a 
record of all functions currently active. If you call foo at Lisp's top level, and it calls bar, which 
in turn calls baz, and baz gets an error, then a backtrace (a backwards trace of the stack) would 
show all of this information. The debugger has two backtrace commands. Control-B simply 
prints out tlie names of tlie functions on the stack; in die above example it would print 
BAZ <- BAR *- FOO <- SI:*EVAL 
<- SI:LISP-T0P-LEVEL1 ^ SI : LISP-TOP-LEVEL 
The arrows indicate the direction of calling. The Meta-B command prints a more extensive 
backtrace, indicating the names of the arguments to the functions and their current values; for 
the example above it might look like: 



SRC:<I ..M AN>DHBUG.THXT.6 24-J AN-83 



Lisp Machine Manual 583 Ihc Debugger 



BAZ: 

Arg (X): 13 
Arg 1 (Y): 1 

BAR: 

Arg (ADDEND): 13 

FOO: 

Arg (FROB): (A B C . D) 
and so on. 

Moving around in the stack: 

Tlie Control -N command moves "down" to the "next" frame (that is, it changes the current 
frame to be the frame tliat called it), and prints out the frame in this sam_e forniat. Control -P 
moves "up" to tlie "previous" frame (the one tliat this one called), and prints out the frame in 
the same fonnat. Meta-< moves to the top of the stack, and Meta-> to the bottom; both print 
out the new current frame. Control -S asks you for a string and searches the stack for a frame 
whose executing function's name contains tliat string. That frame becomes current and is printed 
out. These commands are easy to remember since they are analogous to editor commands. 

The Control -Meta-N, Control-Meta-P, and Control -Meta-B commands are like the 
corresponding Control commands but don't censor tlie stack. When running interpreted code, the 
debugger usually tries to skip over frames diat belong to functions of the interpreter, such as 
*eval, prog, and cond, and only show "interesting" functions. Control -Meta-N, Control- 
Meta-P, and Control -Meta-B show everything. They also show frames that are not yet active; 
that is, frames whose arguments are still being computed for functions that are going to be called. 
The Control -Meta-U command goes up the stack to the next interesting function and makes that 
the current frame. 

Meta-L prints out the current frame in "full screen" format, which shows the arguments and 
their values, the local variables and their values, and the machine code with an arrow pointing to 
the next instruction to be executed. Refer to chapter 28, page 602 for help in reading this 
machine code. 

Commands such as Control -N and Control -P, which are meaningful to repeat, take a prefix 
numeric argument and repeat that many types. The numeric argument is typed by using Control 
or Meta and the number keys, as in the editor. Some other commands such as Control -M also 
use the numeric argument. 

Resuming execution: 

Meta-C is similar to Control -C, but in the case of an unbound variable or undefined 
function, actually setqs the variable or defines the function, so that the error will not happen 
again. Control -C (or Resume) provides a replacement value but does not actually change the 
variable. Meta-C proceeds using the proceed type istore- new -value, and is available only if 
that proceed type is provided. 
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Control -R is used to return a value from the current frame; the frame that called that frame 
continues running as if tlic function of the current fraine had returned. This command prompts 
you for a form, which it will evaluate; it returns the resulting value, possibly after confirming it 
with you. 

The Control -T command does a *throw to a given tag with a given value; you arc prompted 
for the tag and the value. 

Control -Meta-R is a variation of Control -R; it starts the current frame over with the same 
function and arguments. If the function has been redefined in the meantime (perhaps you edited 
it and fixed its bug) the new definition is used. Control-Meta-R asks for confirmation before 
doing it. 

Stepping through function calls and returns: 

You can request a trap to the debugger on exit from a particular frame, or the next time a 
fimction is called. 

Each stack frame has a "trap on exit" bit. The Control -X command toggles tills bit. The 
Meta-X command sets the bit to cause a trap for the current frame and all outer frames. If a 
program is in an infinite loop, this is a good way to find out how far back on the stack tiie loop 
is taking place. The Control -Meta-X command clears Uie trap-on-exit bit for the current frame 
and outer frames. 

The Control -D command pr(x:eeds like Control -C but requests a trap the next time a 
function is called. Ihe Meta-D command toggles the u^ap-on-next-call bit for die erring stack 
group, h is useful if you wish to set tiie bit and tiien resume execution with something other 
than Control -C. The function breakon is used to request a trap on calling a particular fijnction. 
Trapping on entry to a frame automatically sets the trap-on-exit bit for tiiat frame; use Control -X 
to clear it if you do not want another trap. 

Transfering to other systems: 

Control -E puts you into the editor, looking at the source code for die function in the current 
frame. This is usefiil when you have found die function that caused tiie error and needs to be 
fixed. ITie editor command Control -Z will return to die debugger, if it is still tiiere. 

Control -M puts you into the editor to mail a bug report. The error message and a backtrace 
are put into tiie editor buffer for you. A numeric argument says how many frames to include in 
the backtrace. 

Control -Meta-W calls the window debugger, a display-oriented debugger. It is not 
documented in tiiis manual, but should be usable without further documentation. 



SRC:<L.MAN>DHBUG.TEXT.6 24-JAN-83 



Lisp Machine Manual 585 ^Ihc Debugger 



Examining and setting tlie arguments, local variables, and values: 

Control -Meta- A takes a numeric argument, n, and prints out tlie value of the n\h argument 
of the current frame. It leaves * set to the value of tlie argument, st) lliat you can use the Lisp 
read -eval- print loop to examine it. It also leaves + set to a locative pointing to the argument 
on the stack, so that you can change that argument (by calling rplacd on the locative). Control - 
Meta-L is similar, but refers to the n\h local variable of the frame. Control -Meta-V refers to 
tlie n\h value this frame has rcuirned (in a trap-on-exit). Control- Meta -F refers to the function 
executing in the frame; it ignores its numeric argument and doesn't allow you to change the 
function. 

Another way to examine and set the arguments, locals and values of a frame is with the 
functions eh-arg, eh-loc, eh-val and eh -fun. Use these functions in expressions you evaluate 
inside tlie debugger, and tliey refer to tlie arguments, locals, values and function, respectively, of 
die debugger's current frame. 

eh-arg arg-number-or-name 

When used in an expression evaluated in tlie debugger, eh-arg returns die value of the 
spccifed argument in the debuggers current frame. Argument names are compared 
ignoring packages; only the pnamc of die symbol you supply is relevant, eh-arg can 
appear in setf and locf to set an argument or get its location. 

eh-loc local- number- or- name 

eh-loc is just like eh-arg but accesses the current frame's locals instead of its arguments. 

eh-val &optional value- number- or- name 

eh-val is used in an expression evaluated in die debugger when the current frame is 
returning muldple values, to examine diose values. This is only useful if the function has 
already begun to return some values (as in a trap-on-exit), since otherwise diey are all nil. 
if a name is specified, it is looked for in die function's lvalues or :return-list declaration, 
if any. 

eh-val can be used with setf and locf. You can make a frame return a specific sequence 
of values by setting all but die last value with eh-val and doing Control -R to return die 
last value. 

eh-val with no argument returns a list of all die values diis frame is returning. 

eh-fun 

eh -fun can be called in an expression being evalued inside die debugger to return die 
function-object being called in die current frame. It can be used widi setf and locf. 
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27.7.4 Summary of Commands 



Control -A 
Control -Meta- A 
Control -B 
Meta-B 
Control- Meta -B 



Print argument list of function in current frame. 

Examine or change the nth argument of the current frame. 

Print brief backtrace. 

Print longer backtrace. 

Print longer backtrace with no censoring of interpreter functions. 



Control-C or Resume Attempt to continue, using tlie first proceed type on the list of available 
ones for this error. 



Meta-C 

Control -D 
Meta-D 

Control -E 
Control- Meta- F 
Control -G or Abort 



Attempt to continue, setqing the unbound variable or othenvise 
"permanently" fixing the error. I'his uses tlic proceed type :store-new- 
value, and is available only if that proceed type is. 

Attempt to continue like Control-C, but trap on the next function call. 

loggle tlie flag tliat causes a trap on the next function call after you 
continue or otherwise exit the debugger. 

Edit the source code for the function in the current frame. 

Set * to the fimction in the current frame. 

Quit to command level. This is not a command, but something you can 
type to escape from typing in a form. 



Control -L or Clear -Screen 

Redisplay error message and current frame. 

Full-screen typeout of current frame. 

Get local variable n. 



Meta-L 

Control- Meta- L 
Control -M 



Control-NorLlne 
Meta-N 

Control- Meta- N 



Send a bug report containing the error message and a backtrace of n 
frames (default is 3). 

Move to next frame. With argument, move down n frames. 

Move to next frame with full-screen typeout. With argument, move down 
n frames. 

Move to next frame even if it is "uninteresting" or still accumulating 
arguments. With argument, move down n frames. 



Control-P or Return Move to previous frame. With argument, move up n frames. 



Meta-P 

Control- Meta -P 

Control -R 
Meta-R 



Move to previous frame with full-screen typeout. With argument, move 
up n frames. 

Move to previous frame even if it is "uninteresting" or still accumulating 
arguments. With argument, move up « frames. 

Return a value from the current frame. 

Return multiple values from the current frame (doesn't work currently). 



SRC:<L.MAN>I)EnUG.TEXT.6 



24-JAN-83 



Lisp Machine Manual 



587 



he Debugger 



Control -Meta-R 

Control -S 
Meta-S 

Control -Meta-S 

Control -T 
Control -Meta-U 
Control -X 

Meta-X 

Control -Meta-X 

Control-Meta-W 
Control-Z or Abort 

? or Help 

Meta-< 

Meta-> 



Rcinvokc tlic function in the current frame (throw back to it and start it 
over at its beginning.) 

Search for a frame containing a specified function. 

Reads the name of a special variable and returns tliat variable's value in 
tlie current frame. Instance variables of self may also be specified even if 
not special. 

Prints a list of special variables bound by the current frame and the values 
tliey arc bound to by the frame. If the frame binds self, all tlie instance 
variables of self are listed even if not special. 

7Tirow a value to a tag. 

Move up tlie stack to the previous "interesting" frame. 

Toggle tlie flag in tlie current frame that causes a trap on exit or throw 
tlirough that frame. 

Set the flag causing a trap on exit or tlirow tlirough die frame for the 
current frame and all the frames outside of it. 

Clear the flag causing a trap on exit or throw through the frame for the 
current frame and all the frames outside of it. 

Call the window-oriented debugger. 

Abort the computation and throw back to the most recent break or 
debugger, to the program's "command level", or to Lisp top level. 

Print a help message. 

Go to top of stack. 

Go to bottom of stack. 



Control -0 through Control -Meta-9 

Numeric arguments to the following command are specified by typing a 
decimal number with Control and/or Meta held down. 



Super- A, etc. 



The commands Super-A, Super-B, etc. are assigned to all the available 
proceed types for this error. 'ITie assignments are different each time the 
debugger is entered, so it prints a list of tliem when it starts up. 



27.7.5 Deexposed Windows and Background Processes 

If the debugger is entered in a window that is not exposed, a notification is used to inform 
you that it has happened. The notification appears cither as a brief message printed inside square 

UrnnVntc nr oc a omoU unnHr»ii/ that nnnc iin u/ith a hripf mPQCaop ITiP nntifiratinn romind<J vnil 

that you can select the window in which the error happened by typing Terminal S. 

If the debugger is entered in a process that has no window or other suitable stream to type 
out on, the window system tries to assign it a "background window" and print a notification to 
tell you it is there. If the window system is in a clean state at the moment, this can be done, 
and you can then type Terminal S to select the background window. 
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However, if the window system cannot notify you, because windows on the screen are locked, 
it can still inform you of the error. The who-line displays a string containing flashing asterisks 
that tells you there are errors in the background. 

At tliis time you can either try using Terminal Control -Clear-Input to unlock the locks and 
allow tlie notification to be printed nonnally, or you can elect to handle the error using the cold- 
load stream by typing Terminal Call. This command nonnally enters a break-loop that uses the 
cold-load stream, but if tliere are any background errors, it offers to enter tlie debugger to handle 
them. 



27.8 Tracing Function Execution 

'Hie trace facility allows the user to trace some functions. When a function is traced, certain 
special actions will be taken when it is called and when it returns. The default tracing action is 
to print a message when the function is called, showing its name and arguments, and another 
message when the function returns, showing its name and valuc(s). 

Tlic trace facility is closely compatible with Maclisp. One invokes it through the trace and 
untrace special forms, whose syntax is described below. Alternatively, you can use the trace 
system by clicking Trace in the system menu, or by using the Meta-X Trace command in the 
editor. ITiis allows you to select the trace options from a menu instead of having to remember 
the following syntax. 

"t I' fl C e Special Form 

A trace form looks like: 

(trace spec-l spec-2 ...) 

Each spec can take any of the following forms: 

a symbol This is a function name, with no options. The flmction will be traced in 

the default way, printing a message each time it is called and each time it 
returns. 

a list {function- name option- 1 option- 2 ...) 

JUnction-name is a symbol and the options control how it is to be traced. 
The various options are listed below. Some options take arguments, which 
should be given immediately following the option name. 

a list [\\uncX\on function- spec option- 1 oplion-2 ...) 

'This is like the previous form except that function-spec need not be a 
symbol (see section 10.2, page 154). It exists because if function-name was 
a list in the previous form, it would instead be interpreted as the 
following form: 

a list {{function- 1 function-2...) option-1 option-2 ...) 

All of the functions are traced with the same options. Each fiinction can 
be either a symbol or a general function-spec. 

The following trace options exist: 
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■.break pred Causes a breakpoint to be entered after printing the entry trace 

information but before applying the traced function to its arguments, if 
and only if pred evaluates to non-nil. During tlie breakpoint, die symbol 
arglist is bound to a list of the arguments of Uie function. 

.exWbreak pred This is just like break except diat die breakpoint is entered after the 

function has been executed and die exit trace information has been 
printed, but before control returns. During die breakpoint, the symbol 
arglist is bound to a list of the arguments of the function, and die 
symbol values is bound to a list of die values diat die function is 
returning. 

:error Causes tlie error handler to be called when die fimction is entered. Use 

Resume (or Control-C) to continue execution of the funcdon. If diis 
option is specified, diere is no printed trace output other dian die error 
message printed by die error handler. This is semi-obsolete, as breakon 
is more convenient and does more exacdy tlie right diing. 

Causes die function to be single-stepped whenever it is called. See die 
documentation on die step facility, section 27.11, page 596. 

Causes trace information to be printed on ftmcdon entry only if pred 
evaluates to non-nil. 

Causes trace informadon to be printed on funcdon exit only if pred 
evaluates to non-nil. 

TTiis specifies bodi :exitcond and :entrycond togedier. 

Causes die function to be traced only when called, direcdy or indirecdy, 
from the specified funcdon function. One can give several trace specs to 
trace, all specifying the same function but with different wherein options, 
so that die funcdon is traced in different ways when called from different 
functions. 

This is diflferent from advise -within, which only affects die function being 
advised when it is called direcdy from die other funcdon. The trace 
:wherein opdon means diat when the traced function is called, die special 
tracing acdons occur if die other function is die caller of diis fijncdon, or 
its caller's caller, or its caller's caller's caller, etc. 

:argpdl/?i/ This specifies a symbol pdl, whose value is inidally set to nil by trace. 

When die function is traced, a list of die current recursion level for die 
function, die ftmction's name, and a list of arguments is consed onto die 
pdl when die funcdon is entered, and cdr'ed back off when die function is 
exited. The pdl can be inspected from widiin a breakpoint, for example, 
and used to determine die very recent history of die funcdon. This option 
can be used with or without printed trace output. Each fiincdon can be 
given its own pdl, or one pdl may serve several functions. 

:entryprint/om2 The form is evaluated and die value is included in die trace message for 

calls to die function. You can give diis option more dian once, and all 
the values will appear, preceded by \\. 



:step 

:entrycond pred 

:exitcond pred 

:cond pred 
:v\ihere\n fiinciion 
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:exitprint/o/7« 'ITic form is evaluated and the value is included in tlie trace message for 

returns from the function. You can give this option more than once, and 
all the values will appear, preceded by \\. 

•.^T\r\\ fonn The form is evaluated and the value is included in the trace messages for 

both calls to and returns from the function. You can give this option 
more tlian once, and all the values will appear, preceded by W. 

:entry list This specifies a list of arbitrary forms whose values are to be printed along 

with the usual entry-trace. The list of resultant values, when printed, is 
preceded by W to separate it from the other infonnation. 

:exit list 'Hiis is similar to entry, but specifies expressions whose values are printed 

with the exit-trace. Again, the list of values printed is preceded by \\. 

:arg :value :both nil These specify which of the usual trace printouts should be enabled. If 
:arg is specified, then on function entry the name of the function and the 
values of its arguments will be printed. If :value is specified, then on 
function exit the returned value(s) of the ftmction will be printed. If 
:both is specified, both of these will be printed. If nil is specified, 
neither will be printed. If none of tliesc four options arc specified the 
default is to :both. If any further options appear after one of tliese, diey 
will not be treated as options! Rather, they will be considered to be 
arbitrary fornis whose values are to be printed on entry and/or exit to the 
function, along with tlie normal trace information. ITie values printed will 
be preceded by a //. and follow any values specified by :entry or :exit. 
Note tliat since these options "swallow" all following options, if one is 
given it should be the last option specified. 

If the variable arglist is used in any of the expressions given for the :cond, :break, :entry, 
or .-exit options, or after the :arg, :value, :both, or nil option, when those expressions are 
evaluated the value of arglist will be bound to a list of the arguments given to the traced 
function. ITius 

{trace {foo :break (null (car arglist)))) 
would cause a break in foo if and only if the first argument to foo is nil. If the :break or :error 
option is used, the variable arglist will be valid inside the break-loop. If you setq arglist, the 
arguments seen by the function will change, arglist should perhaps have a colon, but it can be 
omitted because this is the name of a system function and therefore global. 

Similarly, the variable values will be a list of tlie resulting values of the traced fijnction. For 
obvious reasons, this should be used only with the :exit option. If the :exitbreak option is used, 
the variables values and arglist are valid inside the break-loop. If you setq values, the values 
returned by the fi.mction will change, values should perhaps have a colon, but it can be omitted 
because this is the name of a system function and therefore global. 

The trace specifications may be "factored", as explained above. For example, 
(trace ({foo bar) :break (bad-p arglist) rvalue)) 
is equivalent to 

(trace (foo rbreak (bad-p arglist) :value) 
(bar :break (bad-p arglist) rvalue)) 
Since a list as a function name is interpreted as a list of fijnctions, non-atomic function names 
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(see section 10.2, page 154) are specified as follows: 

(trace (:function ( :method flavor imessage) rbneak t)) 

trace returns as its value a list of names of all functions it traced. If called with no 
arguments, as just (trace), it returns a list of all tlie functions currently being traced. 

If you attempt to trace a function already being traced, trace calls untrace before setting up 
tlie new trace. 

Tracing is implemented with encapsulation (see section 10.10, page 175), so if the ftmction is 
redefined (e.g. with defun or by loading it from a QFASL file) the tracing will be transferred 
from the old definition to the new definition. 

Tracing output is printed on the stream that is the value of trace -output. ITiis is 
synonymous with terminal -io unless you change it. 

untrace Special Form 

untrace is used to undo the effects of trace and restore functions to their normal, 
untraced state, untrace will take multiple specifications, e.g. (untrace foo quux fuphoo). 
Calling untrace with no arguments will untrace all functions currently being traced. 

unlike Maclisp, if tliere is an error trace (or untrace) will invoke the error system and give 
an English message, instead of returning lists with question marks in them. Also, the remtrace 
fijnction is not provided, since it is unnecessary. 

trace-compile-flag Variable 

If the value of trace-compile-flag is non-nil, the functions created by trace will get 
compiled, allowing you to trace special forms such as cond without interfering with the 
execution of tlie tracing functions. The default value of tliis flag is nil. 

You can also cause the tracing of a particular function to be compiled by calling compile - 
encapsulations. Set compile-encapsulations-flag non-nil does what trace-compile-flag does, 
and more; it makes all kinds of encapsulations be compiled. See page 229. 

27.9 Breakon 

The fijnction breakon allows you to request that the debugger be entered whenever a certain 
function is called. 

breakon function-spec &optional condition-form 

Encapsulate the definition of function-spec so that a trap-on-call occurs when it is called. 
This enters the debugger. A trap-on-exit will occur when tlie stack frame is exited. 

If condition-form is non-nil, its value should be a form to be evaluated each time Junction- 
spec is called. The trap occurs only if condition-fonn evaluates to non-nil. Omitting the 
condition-form is equivalent to supplying t. If breakon is called more than once for the 
same function-spec and different condition-forms, the trap occurs if any of the conditions is 
true. 
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Condition brcakons arc useful for causing tJic trap to occur only in a certain stack group. 
This sometimes allows debugging of calls functions that are being used frequently in background 
processes. 

(breakon 'foo '(eq current-stack-group ', current-stack-group) ) 

If you wish to trap on calls to foo when called from the execution of bar, you can use 
{si:function -active- p 'bar) as the condition. If you want to trap only calls made directly from 
bar, tlie thing to do is 

(breakon '(rwithin bar foo)) 
rather than a conditional breakon. 

Another useflil form of conditional breakon allows you to control trapping from the keyboard: 
(breakon 'foo '( tv : key-state ' :mode-lock) ) 
The trap will occur only when the Mode -Lock key is down. ITiis key is not normally used for 
much else. With this technique, you can successfully trap on functions used by tlie debugger! 

unbreakon function-spec &optional conditional-form 

Remove the breakon set on function-spec. If conditional- fomi is specified, remove only 
that condition. Breakons with other conditions are not removed. 

With no arguments, unbreakon removes all breakons from all functions. 

eh :breakon-f unctions Variable 

A list of all ftmction specs on which breakons currently exist 

To cause the encapsulation which implements the breakon to be compiled, call compile - 
encapsulations or set compile-encapsulations-flag non-nil. See page 229. Tliis may eliminate 
some of the problems that occur if you breakon a function such as prog that is used by the 
evaluator. (A conditional to trap only in one stack group will help here also.) 

27.10 Advising a Function 

To advise a function is to tell it to do something extra in addition to its actual definition. It 
is done by means of the function advise. The something extra is called a piece of advice, and it 
can be done before, after, or around the definition itself. The advice and die definition are 
independent, in that changing either one does not interfere with the other. Each function can be 
given any number of pieces of advice. 

Advising is fairly similar to tracing, but its purpose is different. Tracing is intended for 
temporary changes to a fijnction to give the user information about when and how the function is 
called and when and widi what value it returns. Advising is intended for semi-permanent changes 
to what a function actually does, l^he differences between tracing and advising are motivated by 
this difference in goals. 

Advice can be used for testing out a change to a fimction in a way that is easy to retract In 
this case, you would call advise from the terminal. It can also be used for customizing a 
function that is part of a program written by someone else. In this case you would be likely to 
put a call to advise in one of your source files or your login init file (see page 648), rather than 
modifying the other person's source code. 
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Advising is implemented with encapsulation (see section 10.10, page 175), so if the function is 
redefined (e.g. with defun or by loading it from a QFASL file) tlie advice will be transferred 
from tlie old definition to the new definition. 

advise Special Form 

A function is advised by the special form 

(advise function class name position 
forml form2. . . ) 
None of this is evaluated, function is tlie function to put the advice on. It is usually a 
symbol, but any function spec is allowed (see section 10.2, page 154). The forms arc the 
advice; they get evaluated when the function is called, class should be either :before, 
:after, or :around, and says when to execute the advice (before, after, or around the 
execution of the definition of tlie fijnction). The meaning of :around advice is explained 
a couple of sections below. 

name is used to keep track of multiple pieces of advice on the same fimction. name is an 
arbitrary symbol tliat is remembered as the name of this particular piece of advice. If you 
have no name in mind, use nil; then we say the piece of advice is anonymous. A given 
function and class can have any number of pieces of anonymous advice, but it can have 
only one piece of named advice for any one name. If you try to define a second one, it 
replaces the first. Advice for testing purposes is usually anonymous. Advice used for 
customizing someone else's program should usually be named so tliat multiple 
custom izations to one function have separate names. Then, if you reload a customization 
diat is already loaded, it does not get put on twice. 

position says where to put this piece of advice in relation to others of the same class 
already present on the same function. If position is nil, the new advice goes in the 
default position: it usually goes at tlie beginning (where it is executed before die other 
advice), but if it is replacing another piece of advice with the same name, it goes in the 
same place that die old piece of advice was in. 

If you wish to specify the position, position can be the numerical index of which existing 
piece of advice to insert this one before. Zero means at the beginning; a very large 
number means at the end. Or, position can be the name of an existing piece of advice of 
the same class on the same function; the new advice is inserted before that one. 

For example, 

(advise factorial :before negative-arg-check nil 
(if (minusp (first arglist)) 

(ferror nil "factorial of negative argument"))) 
lliis modifies the factorial function so diat if it is called with a negative argument it 
signals an error instead of running forever. 

unadv 1 se Special Form 

(unadvise Junction class position) 
removes pieces of advice. None of its "arguments" are evaluated, function and class have 
the same meaning as they do in the function advise, position specifies which piece of 
advice to remove. It can be the numeric index (zero means the first one) or it can be the 
name of the piece of advice. 
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unadvise can remove more tlian one piece of advice if some of its arguments are missing. 
If position is missing or nil, tlien all advice of the specified class on the specified function 
is removed. If class is missing or nil as well, then all advice on the specified function is 
removed, (unadvise) removes all advice on all functions, since function is not specified. 

ITie follov^'ing are the primitive functions for adding and removing advice. Unlike the above 
special fornis, tliese are functions and can be conveniently used by programs, advise and 
unadvise are actually macros tliat expand into calls to these two. 

si:adviS8-l junction class name position forms 

Adds advice. The arguments have the same meaning as in advise. Note that the forms 
argument is not a &rest argument. 

si:unadvise-l function &optional class position 

Removes advice. If class or position is nil or unspecified, all classes of advice or advice at 
all positions are removed. 

You can find out manually what advice a function has with grindef. which grinds the advice 
on the ftmction as forms that are calls to advise. These are in addition to tlie definition of the 
function. 

To poke around in the advice structure with a program, you must work with the 
encapsulation mechanism's primitives. See section 10.10, page 175. 

To cause the advice to be compiled, call compile -encapsulations or set compile- 
encapsulations-flag non-nil. See page 229. 

si: advised-functions Variable 

A list of all functions which have been advised. 

27.10.1 Designing the Advice 

For advice to interact usefully with the definition and intended purpose of the function, it 
must be able to interface to the data flow and control flow through the function. We provide 
conventions for doing this. 

The list of the arguments to the function can be found in the variable arglist. :before advice 
can replace this list, or an element of it, to change the arguments passed to the definition itself. 
If you replace an element, it is wise to copy the whole list first with 

(setq arglist (copylist arglist)) 
After tlie function's definition has been executed, the list of the values it returned can be found 
in die variable values. :after advice can set this variable or replace its elements to cause different 
values to be returned. 

All the advice is executed within a prog, so any piece of advice can exit the entire function 
with return. The arguments of the return will be returned as the values of the function. No 
fijrther advice will be executed. If a piece of .'before advice docs this, then the function's 
definition will not even be called. 



SRC:<L.MAN>DB-AID.TEXT.5 24-JAN-83 



Lisp Machine Manual 595 Advising a Function 



27.10.2 -.around Advice 

A piece of :before or :after advice is executed entirely before or entirely after tlie definition 
of the function. :around advice is wrapped around tlie definition; tliat is, the call to the original 
definition of the ftjnction is done at a specified place inside tlie piece of :around advice. You 
specify where by putting die symbol :do-it in that place. 

For example, (+ 5 :do-it) as a piece of :around advice would add 5 to tlie value returned 
by the function. ITiis could also be done by (setq values (list (+ 5 (car values)))) as :after 
advice. 

When there is more than one piece of :around advice, the pieces are stored in a sequence 
just like :before and :after advice. Then, die first piece of advice in the sequence is the one 
started first. The second piece is substituted for :do-it in die first one. The third one is 
substituted for :do-it in the second one. The original definition is substituted for :do-it in die 
last piece of advice. 

:around advice can access arglist, but values is not set up until die outennost :around 
advice returns. At that time, it is set to die value returned by tlie :around advice. It is 
reasonable for die advice to receive die values of die :do-it (e.g. with multiple-value-list) and 
fool with diem before returning diem (e.g. with values-list). 

•.around advice can return from die prog at any dme, whedier die original definition has 
been executed yet or not. It can also override die original definition by failing to contain :do-it. 
Containing two instances of :do-it may be useful under peculiar circumstances. If you are 
careless, die original definition may be called twice, but something like 

(if (foo) (+ 5 :do-it) (* 2 :do-it)) 
will certainly work reasonably. 

27.10.3 Advising One Function Within Another 

It is possible to advise die function foo only for when it is called direcdy from a specific 
other function bar. You do diis by advising die funcdon specifier (:within bar foo). That works 
by finding all occurrences of foo in die definidon of bar and replacing diem with altered -foo - 
within -bar. This can be done even if bar's definidon is compiled code. The symbol altered - 
foo -with in -bar starts off' widi die symbol foo as its definition; dien die symbol altered -foo - 
within -bar, radier dian foo itself, is advised. ^Hie system remembers diat foo has been replaced 
inside bar, so diat if you change die definidon of bar, or advise it, dien die replacement is 
propagated to die new definition or to die advice. If you remove all die advice on (:within bar 
foo), so diat its definidon becomes die symbol foo again, dien die replacement is unmade and 
everydiing returns to its original state. 

(grindef bar) will print foo where it originally appeared, radier dian altered-foo-wlthln-bar, 
so die replacement will not be seen. Instead, grindef will print out calls to advise to describe all 
die advice diat has been put on foo or anydiing else widiin bar. 

An alternate way of putting on diis sort of advice is to use advise-within. 
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advise-within Special Form 

{advise-within wiihin-function function-to-advise 
class name position 
forms... ) 
advises function- to- advise only when called directly from the function wiihin-function. 'ITie 
other arguments mean the same thing as with advise. None of them are evaluated. 

To remove advice from (:within bar foo), you can use unadvise on that function specifier. 
Alternatively, you can use unadvise-within. 

unadvise-within Special Form 

(unadvise-within within-function function-to-advise class position ) 
removes advice that has been placed on (: within within-function function-to-advise). The 
arguments class and position are interpcreted as for unadvise. For example, if those two 
are omitted, tlien all advice placed on function-to-advise within within-function is removed. 
Additionally, if Jii net ion- to- advise is omitted, all advice on any function within within- 
function is removed. If there arc no arguments, than all advice on one function within 
another is removed. Other pieces of advice, which have been placed on one function and 
not limited to within another, are not removed. 

(unadvise) removes absolutely all advice, including advice for one function within another. 

The ftmction versions of advise -w/ith in and unadvise-within are called si:advise- within- 1 
and si:unadvise-within-1. advise- within and unadvise-within are macros that expand into calls 
to the other two. 



27.11 Stepping Through an Evaluation 

The Step facility gives you the ability to follow every step of the evaluation of a form, and 
examine what is going on. It is analogous to a single-step proceed facility often found in 
machine-language debuggers. If your program is doing something strange, and it isn't obvious 
how it's getting into its strange state, then the stepper is for you. 

There are two ways to enter the stepper. One is by use of the step function. 

step form 

This evaluates ^mz with single stepping. It returns the value of form. 

For example, if you have a function named foo, and typical arguments to it might be t and 
3, you could say 

(step '(foo t 3)) 
and the form (foo t 3) will be evaluated widi single stepping. 

The other way to get into the stepper is to use the :step option of trace (see page 588). If a 
fijnction is traced with the :step option, tlicn whenever that function is called it will be single 
stepped. 
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Note that any function to be stepped must be interpreted; that is, it must be a lambda- 
expression. Compiled code cannot be stepped by the stepper. 

When evaluation is proceeding with single stepping, before any form is evaluated, it is 
(partially) printed out, preceded by a forward arrow (-^) character When a macro is expanded, the 
expansion is printed out preceded by a double arrow (o) character. When a form returns a value, 
the fonn and the values are printed out preceded by a bacicwards arrow (<-) character; if there is 
more than one value being returned, an and-sign (a) character is printed between tlie values. 
When the stepper has evaluated tlie args to a fonn and is about to apply the function, it prints a 
lambda (A) because entering the lambda is the next tiling to be done. 

Since die fonns may be very long, the stepper does not print all of a form; it truncates tlie 
printed representation after a certain number of characters. Also, to show tlie recursion pattern of 
who calls whom in a graphic fashion, it indents each form proportionally to its level of recursion. 

After the stepper prints any of these things, it waits for a command from the user. There are 
several commands to tell the stepper how to proceed, or to look at what is happening. The 
commands are: 

Control -N (Next) 

Step to the Next diing. The stepper continues until the next thing to print out, and it 
accepts another command. 

Space 

Go to the next thing at this level. In other words, continue to evaluate at this level, but 
don't step anything at lower levels. This is a good way to skip over parts of the 
evaluation that don't interest you. 

Control -A (Args) 

Skip over the evaluation of the arguments of this form, but pause in the stepper before 
calling the fimction that is the car of the form. 

Control -U (Up) 

Continue evaluating until we go up one level. This is like the space command, only more 
so; it skips over anything on the current level as well as lower levels. 

Control -X(eXit) 

Exit; finish evaluating without any more stepping. 

Control -T (Type) 

Retype the current form in full (without truncation). 

Control -G (Grind) 

Grind (i.e. prettyprint) the current form. 

Control -E (Editor) 

Switch windows, to the editor. 

Control -B (Breakpoint) 

Breakpoint. 'ITiis command puts you into a breakpoint (i.e. a read-eval-print loop) from 
which you can examine the values of variables and other aspects of the current 
environment. From within this loop, the following variables are available: 
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step- form which is the current form. 

step-values which is the list of returned values. 

step -value which is the first returned value. 

If you change the values of these variables, you will affect execution. 

Control -L 

Clear the screen and redisplay the last 10. pending fonns (forms tliat are being 
evaluated). 

Meta-L 

IJkc Control- L, but doesn't clear the screen. 

Control -Meta-L 

Like Control-L, but redisplays all pending forms. 

? or Help 

Prints d(K;umentation on these commands. 

It is strongly suggested that you write some little function and try the stepper on it. If you 
get a feel for what the stepper does and how it works, you will be able to tell when it is the 
right thing to use to find bugs. 

27.12 Evalhook 

The evalhook facility provides a "hook" into the evaluator; it is a way you can get a Lisp 
form of your choice to be executed whenever the evaluator is called. The stepper uses evalhook, 
and usually it is the only thing that ever needs to. However, if you want to write your own 
stepper or something similar, this is the primitive facility that you can use to do so. The way this 
works is a bit hairy, but unless you need to write your own stepper you don't have to worry 
about it. 

evalhook Variable 

If tlie value of evalhook is non-nil, then special things happen in the evaluator. When a 
foim (any form, even a number or a symbol) is to be evaluated, evalhook is bound to 
nil and the function tliat was evalhook's value is applied to one argument— the form that 
was trying to be evaluated. The value it returns is then returned from the evaluator. 

siiapplyhook Variable 

If the value of sl:applyhook is non-nil, it is used rather than apply the next time the 
interpreter is about to apply a function to its evaluated arguments. 

When eidier the evalhook or the applyhook is called, both variables are bound to nil. They 
are also rebound to nil by break and by the debugger, and setq'ed to nil when errors are 
dismissed by throwing to the Lisp top level loop, l^his provides the ability to escape from this 
mode if something bad happens. 

In order not to impair the efficiency of the Lisp interpreter, several restrictions are imposed 
on the evalhook and applyhook. They apply only to evaluation— whether in a read-eval-print 
loop, internally in evaluating arguments in forms, or by explicit use of tlie function eval. They 
do not have any effect on compiled function references, on use of the function apply, or on the 
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"mapping" functions. (In Zctalisp. as opposed to Maclisp, it is not necessary to do (*rset t) or 
{sstatus evalhook t). Also, Maclisp's special-case check for store is not implemented.) 

evalhook fonn evalhook &optional applyhook 

evalhook is a function that helps exploit the evalhook feature. The form is evaluated 
with evalhook lambda-bound to the function evalhook, and with si:applyhook lambda- 
bound to the function applyhook. 'I'he checking of the hooks is bypassed in the 
evaluation of form itself, but not in any subsidiary evaluations, for instance of arguments 
in the form. This is like a "one-instruction proceed" in a machine-language debugger. 
Example: 

;; This function evaluates a form while printing debugging information, 
(defun hook (x) 
{ terpri ) 
(evalhook x 'hook-function)) 

;; Notice how this function calls evalhook to evaluate the fonn f, 
;; so as- to hook the sub-forms, 
(defun hook-function (f) 

(let ((v (evalhook f 'hook-function))) 
(format t "form: ~s~7ovalue: ~s~7o" f v) 

V)) 

;; This isn't a very good program, since iff uses multiple 
;; values, it will not work. 

The following output might be seen from (hook '(cons (car '(a . b)) 'c)): 
form: (quote (a . b)) 
value: (a . b) 
form: (car (quote (a . b))) 
value: a 
form: (quote c) 
value: c 
(a . c) 

27.13 The MAR 

The MAR facility allows any word or contiguous set of words to be monitored constantly, 
and can cause an error if the words are referenced in a specified manner. 'Vhe name MAR is 
from the similar device on the ITS PDP-lO's; it is an acronym for "Memory Address Register". 
The MAR checking is done by the Lisp Machine's memory management hardware, so the speed 
of general execution is not significantly slowed down when the MAR is enabled. However, the 
speed of accessing pages of memory containing the locations being checked is slowed down 
somewhat, since every reference involves a microcode trap. 

ITiese are the functions that control the MAR: 
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set -mar location cycle- type &optional n- words 

The set- mar function clears any previous setting of tJie MAR, and sets tlie MAR on n- 
words words, starting at location, location may be any object. Often it will be a locative 
pointer to a cell, probably created with the locf special forni. n- words currently defaults 
to 1, but eventually it may default to the si/e of the object, cycle- type says under what 
conditions to trap. :read means that only reading the location should cause an error, 
:write means that only writing the location should, t means tliat both should. To set the 
MAR to detect setq (and binding) of the variable foo, use 

(set-mar (value-cell-location 'foo) ':write) 

clear-mar 

This turns off tlic MAR. Warm-booting the machine disables tlie MAR but does not turn 
it off, i.e. references to the MARed pages are still slowed down, clear- mar does not 
currently speed tilings back up until tJie next time the pages arc swapped out; tliis may 
be fixed some day. 

mar-mode 

(mar-mode) returns a symbol indicating the current state of the MAR. It returns one of: 

nil The MAR is not set. 

:read The MAR will cause an error if there is a read. 

:write line MAR will cause an error if there is a write. 

t The MAR will cause an error if there is any reference. 

Note that using the MAR makes tlie pages on which it is set somewhat slower to access, until 
the next time diey are swapped out and back in again after the MAR is shut off. Also, use of 
the MAR currently breaks the read-only feature if those pages were read-only. 

Proceeding from a MAR break allows the memory reference that got an error to take place, 
and continues the program with the MAR still effective. When proceeding from a write, you 
have the choice of whether to allow the write to take place or to inhibit it, leaving the location 
with its old contents. 

sys:mar-break (condition) Condition 

This is the condition, not an error, signaled by a MAR break. 

The condition instance supports these operations: 

iobject The object one of whose words was being referenced. 

ioffset The offset within the object of the word being referenced. 

:value The value read, or to be written. 

rdirection Either :read or :write. 

The prcKeed type :no -action simply proceeds, continuing with the interrupted program as 
if the MAR had not been set. If the trap was due to writing, the proceed type 
:proceed- no -write is also provided, and causes the program to proceed but does not 
store the value in the memory location. 
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Most — but not all— write operations first do a read, setq and rplaca are examples. 'ITiis 
means tliat if the MAR is in :read mode it will catch writes as well as reads; however, they will 
trap during the reading phase, and consequently the data to be written will not be displayed. 
This also means that setting the MAR to t mode causes most writes to trap twice, first for a read 
and tlien again for a write. So when the MAR says tliat it trapped because of a read, tills means 
a read at the hardware level, which may not look like a read in your program. 

27.14 Variable Monitoring 

monitor-variable var &optional current-value- cell- only- p monitor-funclion 

Calls a given function just after a given special variable is setq'cd (by compiled code or 
otherwise). Does not trigger on binding of the variable. The function is given both the 
old and new values as arguments. It does not get the name of tlie variable as an 
argument, so it is usually necessary to use a closure as monitor-funclion in order to 
remember this. 'ITie old value will be nil if tlie variable had been unbound. 

The default monitoring function just prints the symbol and the old and new values. This 
behavior can be changed by specifying the monitor-function argument. 

Normally this feature applies to all setq's, but if current-value-cell-only- p is specified non- 
nil, it applies only to those setq's which would alter the variable's currently active value 
cell. This is only relevant when var is subject to a closure. 

Don't try to use this with variables that are forwarded to A memory (e.g. inhibit - 
scheduling -flag). 

unmonitor-variable &optional var 

If var is being monitored, it is restored to normal. If no var is specified, all variables 
that have been monitored are unmonitored. 
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